Ga naar hoofdinhoud

NL Design System thema maken

Wat is een thema?

Thema's zijn technisch JSON-bestanden waarin design tokens zijn gedefinieerd. Met tooling maken we ze beschikbaar als custom properties in CSS.

Ontwikkel een thema voor jouw organisatie

Als organisatie wordt je onderdeel van de community. De community ontwikkelt white-label componenten: dat betekent dat je nog je eigen invulling moet geven voor de stijl. Werk je voor een organisatie die al vaker projecten doet met NL Design System, dan is er waarschijnlijk al een thema beschikbaar. Ben je nog nieuw, dan kun je een eigen thema beginnen.

Een thema bestaat uit design tokens die in de eerste laag het fundament van de huisstijl beschrijven: denk aan kleuren en typografie. In een diepere laag kun je de designkeuzes van specifieke componenten uitwerken. In een thema leg je dus niet alleen de huisstijl vast, maar ook designkeuzes voor alle white-label componenten die je nodig hebt en waarvan de code reeds is ontwikkeld door teams van andere organisaties.

Speciaal voor thema's van overheidsorganisaties is de themes repository beschikbaar waar je gemakkelijk kunt samenwerken om je eigen thema te publiceren voor interne teams en leveranciers. Het is een handige manier om snel aan de slag te gaan, zonder al te veel onderhoud te moeten doen aan de infrastructuur: het NL Design System kernteam neemt die verantwoordelijkheid. Zo kunnen zelfs teams van overheden en diverse leveranciers samenwerken om een consistente implementatie van de huisstijl te bieden bij alle diensten die de design tokens van NL Design System gebruiken. De thema's worden gecontroleerd door middel van visuele regressietesten

Samengevat is de techniek achter de thema's een verzameling JSON bestanden, waar je voor bestaande componenten de JSON-structuur moet aanhouden die de ontwikkelaars van de component ondersteunen, die met de tool Style Dictionary automatisch worden geconverteerd naar CSS variabelen (en diverse andere formaten). De build van het thema publiceer je als npm-pakketje, zodat developers het makkelijk kunnen installeren en de huisstijl op één plek beheerd kan worden. @utrecht/design-tokens is een voorbeeld van zo'n npm-pakketje.

Wil je een thema voor een andere (commerciële) organisatie ontwikkelen, dan adviseren we om een eigen repository te beginnen op basis van onze example template. Daarmee kun je zelf de infrastructuur onderhouden, en behalve thema's kun je ook componenten ontwikkelen en publiceren.

Design tokens vastleggen

Design tokens kunnen allerlei ontwerpkeuzes bevatten: kleuren, lettergroottes, afstanden en meer. Om een thema te maken vanuit een bestaande website en/of huisstijl maken we vaak een inventarisatie, met als einddoel één of meer JSON-bestanden.

Algemeen

Meestal begint een inventarisatie bij de kleuren. Bij een bestaande site kan dat bijvoorbeeld door individuele kleuren met de developer tools te inspecteren. Met een tool als Project Wallace kun je in één keer de kleuren (en meer) uit een pagina in een overzicht krijgen.

Dat hoeft niet altijd één op één. Soms valt dan op dat sommige kleuren wel erg dicht bij elkaar liggen, dan kan bijvoorbeeld de meest voorkomende gekozen worden en de rest afgerond worden, de afwijking is dan vast eerder een foutje dan een keuze.

Het kan ook zijn dat er duidelijk meerdere varianten zijn van één kleur, bijvoorbeeld drie tinten rood. Je kunt tokens noemen hoe je wilt, het is vaak handig om er iets van een systeem in aan te brengen. Soms kan dat uit een huisstijlgids worden overgenomen. Als er geen bestaand systeem is in de namen, kun je ook de kleurwaarde naar HSL converteren en dan de lightness gebruiken (de “L” uit “HSL”), zodat je bv met rood-30, rood-50 en rood-70. Rond gerust af op hele getallen.

De kleuren zetten we uiteindelijk in een JSON-bestand (in het Design Tokens Format):

{
  "organisatie": {
    "color": {
      "red": {
        "30": { "value": "#911808" },
        "50": { "value": "#f2280d" },
        "70": { "value": "#f77e6e" }
      }
    }
  }
}

Dat bestand kan bijvoorbeeld zo in de filestructuur staan:

├─ src
  ├─ brand
    ├─ organisatie
      ├─ colors.tokens.json

Binnen NL Design System gebruiken we ook design tokens voor andere designkeuzes, waaronder:

  • typografie (lettertypes, groottes en gewichten)
  • spacing
  • focus styles

Componenten en variabelen

Als de algemene tokens zijn gemaakt, kan er ook per component een bestand met tokens worden toegevoegd, waarin ook naar de andere beschikbare tokens kan worden verwezen, zelfs in andere organisaties. In het volgende voorbeeld wordt bijvoorbeeld in de tokens voor de link component van organisatie verwezen naar een kleur rood van andereOrganisatie, met de verwijzing in curly brackets:

{
  "organisatie": {
    "link": {
      "color": { "value": "{andereOrganisatie.color.red.45}" }
    }
  }
}

Meer over design tokens vastleggen

Design tokens inzetten

Zoals genoemd kunnen deze JSON-bestanden in allerlei toepassingen worden gebruikt. Bij NL Design System zorgt Style Dictionary dat de tokens bruikbaar worden in CSS, door een design-tokens.css te genereren. Die output kan er bijvoorbeeld zo uit zien:

/**
  * Do not edit directly
  * Generated at […]
  */
.organisatie-theme {
  --organisatie-color-red-30: #911808;
  --organisatie-color-red-50: #f2280d;
  --organisatie-color-red-70: #f77e6e;
}

In dit bestand worden alle tokens die in het theme van deze organisatie bestaan vanuit verschillende plekken bij elkaar gezet, als custom properties. Nu kunnen ze in de CSS van deze organisatie worden gebruikt, op pagina's waar de organisatie-theme classname op de body staat. Er is ook een output setting waar de variabelen op :root worden geplaatst, voor als de HTML niet makkelijk aanpasbaar is.

Referencing/aliasing is de feature in Style Dictionary die zorgt dat tokens als variabele kunnen worden ingezet, zoals we in het vorige voorbeeld deden met tokens uit een andere organisatie. In de NL Design System configuratie worden alle tokenbestanden meegenomen (met **/*). Ook worden de gebruikte verwijzingen opgenomen als verwijzingen naar CSS, wat extra handig is in het geval van updates.

Werken met design tokens

Meer weten over werken met design tokens? In onderstaande video vertelt Yolijn meer over uitbreiden van bestaande design tokens met jouw designkeuzes.