Stappenplan: Community door het kernteam

Het kernteam volgt dit stappenplan om een component van alle checkpoints 🚩 te voorzien die nodig zijn voor de ‘Community’ status van het Estafettemodel. Organisaties die een component bij willen dragen kunnen het Stappenplan voor organisaties gebruiken.

Onderstaande stappen zijn van toepassing op 1 implementatie uit de community. Alle checks die je uitvoert gelden dus voor deze ene implementatie.

Er kunnen meerdere community implementaties zijn die volledig voldoen, maar voor dit bord kijken we naar een component die het meest ver is. De component heeft een Community status als er minimaal één implementatie beschikbaar is die aan alle checkpoints voldoet. Voordat je begint kies je het Community Componenten bord op GitHub waar de component de meeste checks heeft behaald. Dit bord gebruik je vervolgens om de checks die kijken naar “tenminste één organisatie” mee te beoordelen.

Welke organisatie

Doel

Het kernteam controleert één component tegelijk op de Definition of Done voor Community-componenten.

Actie

Selecteer naar welk organisatiebord je hebt gekeken voor de Definition of Done van ‘Community’ status.

🚩 Checkpoint: Welk bord

Beschikbaar in CSS

Doel

Developers kunnen een component parallel in meerdere frameworks implementeren, zonder de CSS te herhalen.

Verbeteringen die in de CSS worden gedaan, werken door in alle implementaties van de component.

Developers voor een specifiek framework werken niet elk aan een afzonderlijke CSS-implementatie, maar ze werken efficient samen om een gedeelde CSS-implementatie te verbeteren.

De CSS-implementatie krijgt een hogere kwaliteit, wanneer een grotere groep developers betrokken is.

Actie

De component moet beschikbaar zijn in code. Minimaal als HTML/CSS.

Check of de gekozen organisatie hieraan voldoet. Dit doe je door de component te bekijken via de ‘GitHub URL (CSS)’ die in het Communitybord is ingevuld.

De GitHub omgeving moet te bekijken zijn zonder dat je moet inloggen.

🚩 Checkpoint: GitHub (CSS)

Publiek beschikbaar in Storybook

Doel

Developers hebben documentatie waaruit blijkt welke varianten de component heeft, welke HTML gebruikt wordt, en wat de API is van de component.

Developers hebben documentatie met een werkend voorbeeld van de component.

Actie

De component moet publiek beschikbaar zijn in Storybook.

Check of de gekozen organisatie hieraan voldoet. Dit doe je door de component te bekijken via de ‘Storybook URL (CSS)’ die in het Communitybord is ingevuld.

De Storybook omgeving moet te bekijken zijn zonder te hoeven inloggen.

🚩 Checkpoint: Storybook (CSS)

Implementatie voldoet aan naam en beschrijving uit de GitHub Discussion

Doel

De implementatie van de component voldoet aan de verwachtingen, die gebruikers hebben op basis van de naam en de beschrijving van de component op de website van het design system.

Actie

In de GitHub Discussion van de component staan de naam en de beschrijving genoteerd. Check of de implementatie van de gekozen organisatie hieraan voldoet. Dit doe je door de component te bekijken via de ‘Storybook URL (CSS)’ die in het Communitybord is ingevuld.

Vervolgens heb je twee opties:

• Komt de naam van de component overeen met de naam uit de GitHub Discussion? Dan selecteer je ‘Done’.
• Komt de naam niet overeen maar voldoet de implementatie verder wel? Dan selecteer je ‘Done met Alias’.

Tip! Met implementatie bedoelen we bijvoorbeeld utrecht-button of ams-button. Een specifiek type van een implementatie, bijvoorbeeld zonnedael-sparkly-button, noemen we een variant.

🚩 Checkpoint: Implementatie voldoet

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

Doel

De component kan gebruikt worden in pagina’s met andere huisstijlen, zonder dat het visueel ontwerp van dit onderdeel opvallend afwijkt van de rest van de pagina.

Het is makkelijk om een component als white-label component te publiceren, door het aanbieden van een beperkte set standaard design tokens.

Actie

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.

Check of de implementatie van de gekozen organisatie hieraan voldoet. Dit doe je door de component te bekijken via de ‘Storybook URL (CSS)’ die in het Communitybord is ingevuld.

Tip! Om te controleren of er design tokens zijn toegepast kun je gebruik maken van de ‘Inspect’ functionaliteit van je browser. Wanneer je in de CSS verwijzingen ziet naar CSS variabelen zoals bijvoorbeeld --denhaag-button-primary-action-background-color of --ams-button-font-family kun je er vanuit gaan 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

API’s zoals design tokens hebben een prefix van de verantwoordelijke organisatie

Doel

Gebruikers kunnen componenten uit verschillende design systems combineren, zonder dat ze elkaars werking verstoren.

Actie

Om componenten van elkaar te kunnen gebruiken is het toevoegen van een prefix zoals bijvoorbeeld utrecht- of ams- verplicht.

Check of de prefix van de gekozen organisatie is toegevoegd aan de onderstaande onderdelen:

• CSS class selectors.
• CSS variables.
• Design tokens in JSON.

🚩 Checkpoint: Prefix

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.

Actie

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.

Check of de implementatie van de gekozen organisatie hieraan voldoet.

🚩 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.

Actie

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

Check of de gekozen 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.

Actie

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

Check of de gekozen 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

Beschikbaar in de Storybook met alle NL Design System thema’s

Doel

Het is voldoende om alleen te testen met de eigen huisstijl, wanneer je een white-label component deelt met de community, omdat testen met andere huisstijlen door anderen wordt gedaan.

Wanneer de wijziging van een white-label component gevolgen heeft voor andere huisstijlen, dan wordt dit automatisch herkend door een visuele regressietest.

Actie

Als kernteam maken we de component beschikbaar in de ‘Themes’ repository, zodat deze terug te vinden is in de Storybook met alle NL Design System thema’s. Andere organisaties kunnen de component vervolgens gebruiken.

🚩 Checkpoint: Storybook thema’s

Git repository kan gebruikt worden voor doorontwikkeling

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.

Actie

• Maak een clone van de Git repository.
• Volg de instructies in de README.md.
• Controleer dat je alle dependencies kunt installeren.
• Controleer dat je de component kunt builden, indien er een buildproces is.
• Controleer dat je de documentatie kan opstarten, indien aanwezig.
• Controleer dat je de testautomatisering kunt gebruiken, indien aanwezig.
• Controleer dat al bekende bugs publiek worden bijgehouden.

Externe developers kunnen bijdragen

Doel

De repository kan door externe developers gebruikt worden voor doorontwikkeling van de component.

Developers hebben de mogelijkheid om een bug fixen in een component, zelfs als ze de component niet zelf hebben ontwikkeld.

Developers die een bugfix willen bijdragen hebben een prettige ervaring die voldoet aan de verwachtingen, en hebben geen aanleiding om liever de component in eigen beheer te hebben.

Actie

• Controleer dat een Code of Conduct wordt gebruikt die een veilige omgeving biedt.
• Controleer dat er een CONTRIBUTING.md is.
• Controleer dat je een Pull Request kan maken.
• Controleer dat er issues gemeld kunnen worden in een publieke issue tracker.

Visuele regressietests zijn beschikbaar in de Thema Storybook

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.

Actie

• Controleer dat de component in de Storybook van de themes repository staat, met tenminste het Start-thema en Voorbeeld-thema.

🚩 Checkpoint: Visuele regressietest

Beschikbaar in de NL Design System Figma bibliotheek

Doel

Designers kunnen alle componenten direct gebruiken in hun Figma ontwerpen door te koppelen met de NL Design System Figma bibliotheek, en elke component met een code-implementatie is beschikaar.

Developers kunnen ontwerpen in Figma gebruiken om te vinden welke component-implementaties ze kunnen gebruiken in code, doordat het ontwerp is voorzien van links naar alle relevante informatie.

Er worden vaker toegankelijke componenten uit het design system gebruikt, doordat designers dit aanbevelen aan developers voordat de ontwikkeling van een website begint.

Gebruikers van de Basis-tokens kunnen gebruik maken van de nieuwe component door de component design tokens over te nemen van het Start-thema.

De component kan met het Voorbeeld-thema gebruikt worden in voorbeelden, templates en patronen.

Actie

• Als kernteam nemen we de component over uit de Figma omgeving van de gekozen organisatie, inclusief de bijbehorende design tokens.
• Plaats de component in de NL Design System Figma bibliotheek.
• Voeg de component toe aan het Start-thema.
• Voeg de component toe aan het Voorbeeld-thema.
• Heeft de gekozen organisatie geen Figma component? Dan ontwikkelen we deze als kernteam zelf.

Organisaties die de NL Design System Figma bibliotheek vanaf dat moment dupliceren, krijgen de component direct meegeleverd. Organisaties die de NL Design System Figma bibliotheek al hadden gedupliceerd, worden op basis van de Figma changelog geïnformeerd over hoe ze dit component ook kunnen overnemen.

• 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.
• Plak de URL in de kolom ‘Figma URL’ van het Community projectbord.
• Had de gekozen organisatie zelf geen Figma component? Plak de URL dan óók in het projectbord voor deze organisatie.

🚩 Checkpoint: Figma URL

Beschikbaar in de NL Design System Component assessment (Figma)

Doel

Developers kunnen ontwerpen in Figma gebruiken om te vinden welke component-implementaties ze kunnen gebruiken in code, zelfs wanneer de designs niet gemaakt zijn met de bijbehorende Figma-componenten, doordat het ontwerp is voorzien van links naar alle relevante informatie.

Er worden vaker toegankelijke componenten uit het design system gebruikt, doordat designers dit aanbevelen aan developers voordat de ontwikkeling van een website begint.

Actie

Het kernteam voegt een ‘Component sticker’ toe aan het Figma bestand ‘NL Design System Component assessment’. Deze sticker linkt naar de documentatiepagina van de component op nldesignsystem.nl.

Door deze ‘Component stickers’ op screenshots te plakken, kunnen we geïnteresseerde organisaties inzicht bieden welke componenten beschikbaar zijn om hun website of applicatie mee op te bouwen.

🚩 Checkpoint: Component assessment

Backup van de code

Doel

Gebruikers kunnen vertrouwen dat de code van de componenten die ze gebruiken langdurig beschikbaar is voor doorontwikkeling.

Gebruikers kunnen vertrouwen dat er backups zijn van de componenten die ze gebruiken.

Actie

Als de component wordt ontwikkeld met de NL Design System infrastructuur op github.com/nl-design-system, dan wordt al automatisch een backup gemaakt van de code met Rewind.

Als code van de component in eigen infrastructuur wordt ontwikkeld, dan moet handmatig een automatische backup ingesteld worden. Neem contact op met het kernteam, en vraag om een automatisch dagelijks een mirror te maken van jouw Git repository naar een repository bij NL Design System. De backup-repository zal private zijn, zodat geen verwarring ontstaat wat de originele repository is, en voorkom je dat de backup-repository hoger kan eindigen in zoekresultaten.

Status bijgewerkt naar Community

Doel

Gebruikers kunnen herkennen dat de component klaar is om te gebruiken in eigen projecten door de badge “Community”.

Actie

• Verander de Status van het backlog issue naar in het projectenbord Components - 2 - Community naar ‘Community’.
• Verander het label ‘Help Wanted’ van het backlog issue naar ‘Community’.
• Verander het label ‘Help Wanted’ van de GitHub Discussion naar ‘Community’.
• Selecteer bij ‘Projects’ het volgende projectenbord: Components - 3 - Candidate.
• Filter het Candidate bord op de component door te zoeken op {naam-component}.
• Kopieer de URL na het filteren.
• Voeg onderstaande tekst toe als comment aan de GitHub Discussion.

## ✨ Dit component is nu Community ✨

Help je mee hem door de Candidate stappen te krijgen?
[{naam-component} op het Candidate bord]({url-candidate-bord})

🚩 Checkpoint: Status

Over promotie

Zet het checkpoint ‘Promotie’ op ‘Done’ of ‘Scheduled’ vóór de promotie heeft plaatsgevonden. Dit doen we omdat de status ‘Community’ pas zichtbaar wordt nadat alle checkpoint zijn behaald.

🚩 Checkpoint: Promotie

Informatie van de component bijgewerkt op nldesignsystem.nl

Doel

Op nldesignsystem.nl is de meest recente informatie van de component beschikbaar, op het moment dat de component wordt gepromoot door het kernteam.

Actie

• Publiceer een nieuwe versie van het component-progress package: ga naar de pull requests van de Index repository en zoek naar de pull request genaamd docs(release): design system packages. Approve en merge de pull request. Deze pull request word automatisch aangemaakt elke keer wanneer de vorige is gemerged.
• Wacht tot @nl-design-system/component-progress op npm is bijgewerkt. Je kunt dit controleren door te kijken naar de datum bij Last publish.
• Open de documentatie repository in Visual Studio Code.
• Update @nl-design-system/component-progress in de documentatie repository. Dat doe je door lokaal in de branch pnpm install @nl-design-system/component-progress@latest --save-dev -w te draaien. Dit update de devDependency en de lockfile.
• Maak een nieuwe branch aan en gebruik de volgende naam:

Branch

build/update-component-progress-{datum-of-versienummer}

• Maak een commit en gebruik hierbij het volgende bericht:

Commit Message

build: update component progress {versienummer}

• Publiceer je branch naar GitHub om een pull request (PR) aan te maken.
• Ga naar GitHub en gebruik de volgende opzet voor je PR:

Title

build: update component progress {versienummer}

Description

This PR will update the component progress to version {versienummer}.

• Klik op ‘Create Pull Request’
• Geef een developer uit het kernteam via Slack een seintje dat de PR klaar staat.

🚩 Checkpoint: nldesignsystem.nl

Gebruik van component uit de community gepromoot

Doel

De community weet dat hun inzet om de component te maken wordt gewaardeerd.

Bekendheid geven aan een component die een nieuwe implementatie heeft.

Gebruikers aanmoedigen een nieuwe component toe te passen in hun eigen huisstijl, in eigen code en in eigen ontwerpen, en daar feedback over te geven.

Actie

• Voeg het label ’📣 Promotion’ toe aan het backlog issue.

Communityleden selecteren voor credits

Het kernteam selecteert communityleden om credits toe te kennen. Dit kan bijvoorbeeld de maintainer van Storybook zijn of de betrokken designer. Activiteit in de Discussion of commits in de code van het community component kunnen hierbij als basis dienen.

Slack

Plaats dit bericht in #nl-design-system en vul het aan waar nodig.

✨ {naam-component} is nu Community ✨

Met dank aan {persoon/personen} van {organisatie} is {naam-component} nu beschikbaar in de Community!

[Bekijk {naam-component}]({url-nldesignsystem.nl}): {beschrijving-component}

Help je mee {naam-component} naar Candidate te brengen? Dat doe je bijvoorbeeld door ons in de [GitHub Discussion voor de {naam-component} component]({url-github-discussion}) te laten weten waar je {naam-component} component gebruikt.

Heartbeat, Nieuwsbrief en LinkedIn

Vanuit het kernteam benaderen we de organisatie die de component heeft ontwikkeld. We vragen of zij de component tijdens een Heartbeat willen presenteren. Als dit niet mogelijk is, nemen wij als kernteam deze taak op ons.

Daarnaast plaatsen we een bericht in de nieuwsbrief en op LinkedIn.

Promoties hoeven niet altijd dezelfde vorm aan te houden. Gebruik onderstaande punten als voorzet:

• Naam van de component.
• Beschrijving van de component.
• URL van de component op nldesignsystem.nl
• URL van de GitHub Discussion.
• Credits: persoon/personen van organisatie, eventueel gecombineerd met een kort interview.

Promoties kunnen ook gecombineerd worden wanneer meerdere componenten van status veranderen.

🏁 Finish

Zo wat een werk! Je hebt alle stappen genomen en zo alle checkpoints behaald die nodig zijn voor de ‘Community’ status van het Estafettemodel. De component gaat nu door voor de ‘Candidate’ status.