TODO: PageHeader

Hoofdmenu

Design Token conventies

We gebruiken het Design Tokens formaat dat nog actief wordt ontwikkeld door de Design Tokens Community Group bij het W3C. Dat is een eenvoudig JSON-formaat om design keuzes uit te wisselen tussen systemen. De structuur die we gebruiken is als volgt voor componenten:

{
  "prefix": {
    "component": {
      "color": {
        "$value": "#007DAD"
      }
    }
  }
}

De structuur van design tokens

Onderdelen van een component

Gebruik de namen die overeenkomen met de anatomie van de component. De namen komen vaak overeen met de structuur van BEM class names in CSS.

Heeft een component een onderdeel (een “Element” in BEM), dan kun je dat gebruiken als onderdeel van de naam. Bijvoorbeeld placeholder in example.text-input.placeholder.color.

Heeft een component een variant, dan kun je die gebruiken als onderdeel van de naam. Bijvoorbeeld: lead in example.paragraph.lead.font-size.

Heeft een component een state, dan kun je die gebruiken als onderdeel van de naam. Bijvoorbeeld: disabled in example.button.disabled.cursor.

Property namen

CSS property namen die we al gebruiken als design tokens:

Gebruik CSS logical properties waar mogelijk, zodat de component voor internationalisatie voldoet aan de Definition of Done.

Gebruik de volgende CSS properties in principe niet. Dit zijn geen CSS logical properties.

We gebruiken de volgende namen voor states, die uit CSS, HTML en ARIA komen:

Platformonafhankelijke tokens

Gebruik design tokens met name voor designkeuzes die je op een implementatie- en platformonafhankelijke manier kunt uitdrukken. Waarden zoals kleuren en lengtes. Goede platform-onafhankelijk waarden zijn bijvoorbeeld:

Dit soort waarden hebben de voorkeur boven waarden die alleen in CSS worden ondersteund, en bijvoorbeeld niet in Android en Figma:

Als je een component wilt maken met twee varianten, dan moet je dat niet altijd met design tokens oplossen. Gebruik bijvoorbeeld de volgende CSS properties niet voor design tokens:

Je mag natuurlijk wel voor intern gebruik CSS variables gebruiken voor deze CSS properties.

Essentiële tokens voor white-label componenten

Bied voldoende tokens aan om jouw white-label component aanpasbaar te maken voor de huisstijl van andere teams. Bekijk de screenshots die verzameld worden van componenten in de GitHub Discussions, en kijk welke designkeuzes verschillen bij de verschillende implementaties. Probeer circa 80% van de toegankelijke designs te ondersteunen.

We maken onderscheid tussen een aantal soorten componenten:

In het algemeen geldt:

Voor inline componenten geldt:

Voor inline block componenten geldt:

Voor block componenten geldt:

Voor layout componenten geldt:

Voor media componenten geldt:

De $value van design tokens

Gebruik design tokens met name voor designkeuzes die je op een implementatie- en platformonafhankelijke manier kunt uitdrukken. Waarden zoals kleuren en lengtes. Goede platform-onafhankelijk waarden zijn bijvoorbeeld:

Dit soort waarden hebben de voorkeur boven waarden die alleen in CSS worden ondersteund, en bijvoorbeeld niet in Android en Figma:

Vermijd CSS keywords als design token waarde, want die zijn al helemaal niet platformonafhankelijk. Bijvoorbeeld:

Publiceer een JSON bestand met alleen metadata

Om documentatie van design tokens makkelijk te maken, publiceren we een tokens.json bestand met metadata op npm. Dit bestand heeft geen enkele $value, alleen $extensions en $type.

Het voordeel van deze metadata los beheren, is dat het makkelijk is om metadata op één plek te hebben in plaats van in een heleboel themes.

Naast $extensions bevat het bestand ook $type, op basis van de types van de Design Tokens format.

Bijvoorbeeld, je wilt een tokens.json maken bij de volgende CSS:

.example-button {
  background-color: var(--example-button-background-color);
  font-size: var(--example-button-font-size);
}

Dan kun je de volgende tokens.json meeleveren:

{
  "example": {
    "button": {
      "background-color": {
        "$extensions": {
          "nl.nldesignsystem.css-property-syntax": "<color>",
          "nl.nldesignsystem.figma-implementation": true
        },
        "$type": "color"
      },
      "font-size": {
        "$extensions": {
          "nl.nldesignsystem.css-property-syntax": ["<length>", "<percentage>"],
          "nl.nldesignsystem.figma-implementation": true
        },
        "$type": "fontSizes"
      }
    }
  }
}

We gebruiken op dit moment de volgende extensions: