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