Ga naar hoofdinhoud

Stappenplan: Community voor organisaties

Als je als organisatie een component wilt bijdragen aan NL Design System kun je dit stappenplan volgen.

Voeg de component toe aan de componenten bord

Doel

Overzicht hebben welke stappen nog gedaan moeten worden om een component beschikbaar te maken voor anderen.

Gebruikers kunnen vanuit één plek alle belangrijkste informatie vinden over de verschillende implementaties van een component.

Acties

Heb je nog geen eigen Community Componenten bord op GitHub? Vraag dan aan het kernteam om er een aan te maken.

  1. Open het Communitybord via Community Componenten bord op GitHub.
  2. Klik op de + icoon links onderaan de pagina om een component toe te voegen.
  3. Kies Add item from repository.
  4. Selecteer backlog en zoek op de naam van de component.
  5. Selecteer de component.
  6. Kies rechts onderin Add selected items.

🚩 Checkpoint: Title

Prefix van de verantwoordelijke organisatie

Doel

Developers en designers kunnen aan de API prefix zien uit welk design system de component komt.

Acties

Vul de prefix van de organisatie in, bijvoorbeeld utrecht of ams.

🚩 Checkpoint: Organisatie prefix

Naam van de component

Doel

Wanneer een component-implementatie een andere naam heeft gebruikt dan de naam die is gekozen in NL Design System, dan kunnen gebruikers vertrouwen dat de implementatie klopt bij de beschrijving van de component, en dat de implemenatie niet fout is gelinkt.

Acties

Vul de naam van het CSS component in, bijvoorbeeld {prefix-organisatie}-{naam-component}.

🚩 Checkpoint: Naam

Implementatie heeft minimaal kleur en typografie beslissingen met design tokens geïmplementeerd

Doel

Gebruikers die de component in een andere huisstijl willen gebruiken, hoeven de component niet te forken om de huisstijl in te stellen.

De component forken hoeft alleen bij uitzondering, waardoor bugfixes en verbeteringen op één plek terechtkomen, en iedereen er van kan profiteren.

Acties

Door met design tokens te werken zorgen we ervoor dat meerdere organisaties de component van een eigen huisstijl kunnen voorzien. Minimaal zouden er design tokens beschikbaar moeten zijn om kleur en typografie beslissingen door te voeren.

Zorg ervoor dat de component gebruik maakt van de minimale design tokens.

Tip! Om te controleren of er design tokens zijn toegepast, kun je de 'Inspect' functie in je browser gebruiken. Wanneer je in de CSS verwijzingen ziet naar CSS-variabelen zoals bijvoorbeeld --{prefix-organisatie}-button-primary-action-background-color of --{prefix-organisatie}-button-font-family kun je ervan uitgaan dat er design tokens zijn gebruikt.

Tip! Soms heeft een component geen specifieke design tokens nodig. Denk bijvoorbeeld aan design tokens voor font-family bij componenten zoals Mark of Icon. Gebruik in dit soort gevallen je gezonde verstand.

🚩 Checkpoint: Minimale design tokens

Gebruikte design tokens voldoen aan naamgeving conventie van NL Design System

Doel

Gebruikers die het design van een component willen instellen, kunnen voorspellen wat de naam is van de design tokens die ze moeten instellen.

Gebruikers kunnen het design van de component instellen met component-tokens, zonder dat het noodzakelijk is common tokens of brand tokens in te stellen.

Gebruikers kunnen white-label componenten uit verschillende design systems combineren, zonder dat het noodzakelijk is common tokens van meerdere design systems in te stellen.

Acties

Voor NL Design System zijn er afspraken gemaakt voor duidelijke en voorspelbare namen. De beschikbare design tokens van een component moeten voldoen aan de naamgeving conventie van NL Design System. Zo is een component herbruikbaar voor alle verschillende thema's.

Zorg ervoor dat de design tokens voldoen aan de naamgevingsconventie.

🚩 Checkpoint: Naamgeving design tokens

EUPL-1.2 licentie toegepast

Doel

De component mag door andere organisaties gebruikt worden, zodat de investering grotere waarde oplevert.

Verbeteringen die anderen bijdragen aan de component, kunnen toegevoegd worden aan de code zonder juridische problemen te veroorzaken.

Developers van organisaties die waarschijnlijk willen bijdragen, hebben geen juridische belemmeringen om bij te dragen.

Producten die met de component gemaakt worden hoeven niet per se open source te zijn, zodat zoveel mogelijk websites toegankelijker en gebruiksvriendelijker gemaakt kunnen worden.

Acties

Binnen het NL Design System werken we voor componenten met de Openbare Licentie van de Europese Unie (EUPL-1.2).

Zorg ervoor dat de organisatie naar de EUPL-1.2 licentie verwijst op de onderstaande posities:

  • GitHub repository: Als één van de repository details onder 'About' in de sidebar.
  • Package in npm: Onder 'License' in de sidebar.
  • Storybook: Als een aparte pagina binnen de sidebar, of binnen de introductiepagina danwel README.
  • Figma (optioneel): Op de cover of direct naast de cover van de Figma bibliotheek.

🚩 Checkpoint: Licentie component

Documentatie heeft de Creative Commons 0 licentie (CC0)

Doel

Anderen kunnen onvoorwaardelijk de documentatie hergebruiken, aanpassen, vertalen en op nieuwe manieren gebruiken.

Wanneer anderen een eigen implementatie van een component maken, kunnen ze delen van de documentatie hergebruiken, en daarmee sneller een de definition of done voldoen.

Doordat bronvermelding en auteursrechten vermelden niet nodig is, kan iedereen moeiteloos de documentatie gebruiken op eigen manieren.

Het is duidelijk dat de documentatie auteursrechtenvrij is, en niet dezelfde licentie heeft als de code.

Acties

Binnen het NL Design System werken we voor de documentatie met de Creative Commons 0 licentie (CC0).

Zorg ervoor dat de organisatie de CC0 licentie benoemt in het README.md bestand van de component in GitHub.

Tip! Door de 'Code' of 'Raw' weergave van het README.md bestand te bekijken zou je bovenaan <!-- @license CC0-1.0 --> moeten zien staan.

🚩 Checkpoint: Licentie documentatie

Component te gebruiken door designers

Doel

Designers kunnen vanaf de NL Design System website met één klik de Figma-component openen, zonder door het Figma bestand te zoeken.

Acties

Kopieer de URL van de componentpagina door in Figma met de rechtermuisknop op de component in de sidebar te klikken en 'Copy link to page' te selecteren.

🚩 Checkpoint: Figma URL

Component te installeren door developers

Doel

Developers kunnen vanaf de NL Design System website met één klik de "npm install" command kopieren, zonder te zoeken op npmjs.com.

Componenten kunnen gemakkelijk geïnstalleerd worden en up-to-date gehouden worden in projecten.

Developers hoeven de code van een component-implementatie niet te kopieeren om de component te gebruiken, omdat het makkelijker is de code via een package manager te installeren als dependency voor hun project.

Developers kunnen aan @organisatie/ in de naam van de npm package herkennen dat de component nog niet helemaal stabiel is en door welke organisatie deze is ontwikkeld.

Acties

Vul de https://www.npmjs.com URL van het css component in. Is er geen losse package voor de component en is deze onderdeel van een css bibliotheek? Vul dan de url van de bibliotheek in.

Let op! Is de component alleen beschikbaar in React? Dan kan deze stap helaas niet worden gechecked.

🚩 Checkpoint: npm URL (CSS)

Component documentatie beschikbaar voor developers

Doel

Developers kunnen de component makkelijk gebruiken doordat elke variant gedocumenteerd is en een codevoorbeeld heeft.

Gebruikers kunnen succesvol aan de slag met de component, doordat de codevoorbeelden kloppen bij de versie van de component.

De makers van de component kunnen gemakkelijk en snel controleren of alle codevoorbeelden in de documentatie nog werken, wanneer ze wijzigingen doen aan de component.

Acties

Vul de storybook URL in van de default story in de CSS Storybook.

Is er alleen een React Storybook? Zorg dan dat een codevoorbeeld van CSS beschikbaar is voor alle stories en vul de URL in waarop deze beschikbaar zijn.

🚩 Checkpoint: Storybook URL (CSS)

Component heeft visuele regressietests

Doel

Wanneer een wijziging zichtbaar de bestaande werking van de component verstoort, dan wordt dit automatisch herkend door een visuele regressietest, en de wijziging wordt op die grond afgewezen.

Voorkomen dat externe bijdragen veel tijd kosten om te reviewen.

Voorkomen dat pas in productie wordt opgemerkt dat de bestaande werking van een component is verstoord, door een bijdrage die alleen voordeel had voor externe gebruikers van de white-label component.

Voorkomen de makers van de component geen externe bijdragen meer willen accepteren, omdat die meer problemen opleveren dan voordeel bieden.

Acties

Als de component wordt ontwikkeld met de NL Design System infrastructuur op github.com/nl-design-system, dan heb je automatisch toegang tot visuele regressietest met Chromatic.

Controleer dan dat "Storybook Publish" en "UI Tests" bij de Pull Request checks staan.

Component beschikbaar voor visuele regressietests

Doel

Met het Voorbeeld-thema kan getest worden worden of de essentiële design tokens in code en design werken.

Er wordt aangetoond dat de npm package van de component ook werkt als dependency in andere projecten.

Organisaties die wel een eigen huisstijl hebben, maar geen eigen Storybook, kunnen met visuele regressietests controleren dat nieuwe versies van componenten goed blijven werken in combinatie met hun huisstijl.

Acties

  1. Clone de http://github.com/nl-design-system/themes repository.
  2. Zorg dat je pnpm hebt geinstalleerd.
  3. Installeer de dependencies van de repository met het commando: pnpm install.
  4. Maak de design tokens beschikbaar voor Storybook door pnpm run build uit te voeren.
  5. Draai Storybook met: pnpm run storybook.

Voeg de story toe aan de Components sectie in Storybook

Doel

Doel: makkelijk maken voor developers om de component te vinden in de themes Storybook en eventueel te vergelijken met andere component implementaties.

Importeer de design tokens

Tip: Worden de design tokens van de organisatie al geimporteerd in /packages/storybook/config/preview.ts? Ga dan door naar de volgende sectie.

Importeer de design tokens van de organisatie in /packages/storybook/config/preview.ts:

import "@example/organisatie-design-tokens/dist/index.css";

Importeer het custom font

Tip: Heeft de organisatie geen custom font, gelden er auteursrechten op het font of word het custom font van de organisatie al geimporteerd in /packages/storybook/config/preview.ts? Ga dan door naar de volgende sectie.

Importeer het custom font van de organisatie in /packages/storybook/config/preview.ts:

import "@example/organisatie-design-tokens/src/font";

Maak een story bestand aan

  1. Ga naar packages/voorbeeld-design-tokens/documentation.
  2. Maak een mapje aan voor de component met de naam zoals beschreven bij NL Design System, of open het bestaande mapje om een component van een extra organisatie toe te voegen.
  3. Maak een nieuw bestand aan met de naam {prefix-organisatie}-{naam-component}.stories.tsx.

Voeg de component toe aan de story

// packages/voorbeeld-design-tokens/documentation/{naam-component}/{prefix-organisatie}-{naam-component}.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { ComponentNaam } from "{react-component-library-package}";


const meta = {
  id: "{prefix-organisatie}-{naam-component}",
  title: "Components/{Component Naam}/{Organisatie Naam}",
  component: ComponentNaam,
  parameters: { actions: { disable: true } },
  args: {
    // ...default arguments for the story
  },
} satisfies Meta<typeof ComponentNaam>;


type Story = StoryObj<typeof meta>;


export default meta;


// Een story met het voorbeeld thema
export const VoorbeeldTheme: Story = {
  name: "Voorbeeld theme",
  parameters: { theme: "voorbeeld-theme" },
};


// Een story met het thema van de organisatie die de component bijdraagt
export const OrganisatieNaamTheme: Story = {
  name: "{Organisatie Naam} theme",
  parameters: { theme: "{prefix-organisatie}-theme" },
};

Voeg de component toe voor visuele regressietests van andere thema's

Doel

Wanneer de huisstijl in de toekomst wordt gemoderniseerd, dan maakt de component het makkelijk om te migreren naar de nieuwe huisstijl.

Wanneer de huisstijl in de toekomst wordt gemoderniseerd, dan behoud je de waardevolle investeringen in de component voor toegankelijkheid, gebruiksvriendelijkheid en robustheid.

Organisaties die meerdere huisstijlen gebruiken, kunnen dezelfde component gebruiken in voor alle huisstijlen.

Voeg organisatie toe aan de theme-toolkit

Tip! Is er al een bestand genaamd packages/theme-toolkit/src/component-stories-{prefix-organisatie}.tsx aanwezig? Ga in dat geval direct verder met de volgende sectie: "Voeg een component toe".

// packages/theme-toolkit/src/component-stories-{prefix-organisatie}.tsx
import { STORY_GROUPS } from "./component-stories-util";
import { ComponentNaam } from "{react-component-library-package}";


export const ORGANISATIE_PREFIX_COMPONENT_STORIES = [
  {
    // De ID die gebruikt wordt in de config.json van organisaties die de component willen gebruiken
    storyId: 'react-{prefix-organisatie}-{naam-component}--default',
    component: '{prefix-organisatie}-{naam-component}',
    // Optioneel: Kies een van de opties van STORY_GROUPS
    group: STORY_GROUPS[],
    name: '{Organisatie Naam} {Component Naam}',
    // De render functie om de component als story te renderen met properties en children zoals nodig als voorbeeld.
    render: () => <></>,
  },
];

Voeg een component toe aan de organisatie in de theme-toolkit

In de array van stories kun je stories toevoegen voor de component. In ieder geval een default story, maar mogelijk ook stories voor de diverse states of varianten van de component waar losse design beslissingen over genomen kunnen worden.

// packages/theme-toolkit/src/component-stories-{prefix-organisatie}.tsx


// De lijst van stories voor alle componenten
export const ORGANISATIE_PREFIX_COMPONENT_STORIES = [
  ...{
    // De ID die gebruikt wordt in de config.json van organisaties die de component willen gebruiken
    storyId:
      '{type-component, nu alleen nog react}-{prefix-organisatie}-{naam-component}--{naam-story, bijvoorbeel default, naam-van-de-variant of naam-van-de-state}',
    component: '{prefix-organisatie}-{naam-component}',
    // Optioneel: Kies een van de opties van STORY_GROUPS
    group: STORY_GROUPS[],
    name: '{Organisatie Naam} {Component Naam}',
    // De render functie om de component als story te renderen met properties en children zoals nodig als voorbeeld.
    render: () => <></>,
  },
];

Maak een Pull Request

Zorg dat de component beschikbaar komt met een Pull Request op GitHub en vraag het kernteam in #nl-design-system-developers om een review.

🚩 Checkpoint: Theme Storybook URL

GitHub URL

Doel

Developers die de component gebruiken kunnen de code zien en suggesties doen voor verbeteringen. Dit helpt het samenwerken aan toegankelijke en gebruiksvriendelijke componenten die voor iedereen bruikbaar zijn.

Gebruikers van de component kunnen bugs en feature requests melden, en er is een publiek overzicht van de meldingen van anderen.

Gebruikers kunnen een backup maken van de code van componenten die ze nodig hebben.

Alle wijzigingen tussen versies van de component zijn voor anderen te controleren.

Acties

  • Ga in GitHub naar de CSS van de component toe en kopieer de URL.
  • Plak deze URL in het juiste veld.

🚩 Checkpoint: GitHub URL (CSS)

Status bijgewerkt naar Available

Doel

Design systems in de community kunnen zelf aangeven of hun component bedoeld is om te delen met anderen via de NL Design System website.

Een nieuwe implementatie van een component vindbaar maken voor de community, op nldesignsystem.nl.

Acties

Zet checkpoint 'Status' op 'Available'.

Breng de community en het kernteam op de hoogte via Slack. De component kan daarna door het kernteam 'Candidate' worden gemaakt.

## 🎉 {naam-component} is nu beschikbaar bij {organisatie} 🎉


📣 Kernteam: Helpen jullie mee de component Community te maken?

Heeft de component al de status 'Community'? Plaats dan het volgende bericht:

## 🎉 {naam-component} is nu beschikbaar bij {organisatie} 🎉


Wat is er nieuw? {beschrijf hier wat er anders is aan deze implementatie ten opzichte van andere community componenten}

🚩 Checkpoint: Status

Heb je een vraag?

Heb je een vraag? Twijfel niet en stel je vraag via het #nl-design-system Slack kanaal van CodeForNL of neem contact op met het kernteam.