Ga naar hoofdinhoud

Componenten bijdragen

Stappenplan: Help Wanted

Volg dit stappenplan om een component van alle checkpoints 🚩 te voorzien die nodig zijn voor de 'Help Wanted' status van het Estafettemodel.

Naam bepaald op basis van NL Design System naamgeving

Begin met het bepalen van een naam.

Baseer de naam van de component indien mogelijk, op herkenbare termen uit webstandaarden. Liever termen uit HTML, CSS, SVG en WAI-ARIA dan uit 'UI frameworks' die op het moment populair zijn. We schrijven componenten over het algemeen als enkelvoud en met kapitalen. Bijvoorbeeld 'Accordion' of 'Text Input'.

Kijk voor inspiratie bijvoorbeeld bij:

Zijn er meerdere namen voor de component? Kies de meest gangbare. De andere namen kun je later toevoegen aan de documentatie.

🚩 Checkpoint: Naam

Component kort beschreven

Doel: Vanuit het componentenoverzicht kan men de juiste component uitzoeken.

De beschrijving biedt een samenvattende omschrijving van de component, zodat deze niet met een ander verward kan worden.

Kijk ter inspiratie bij in het componentenoverzicht. Of bij de volgende design systems:

Beschrijf specifiek, kort en bondig wat de definitie is voor de component. We schrijven definities over het algemeen niet langer dan één zin, maar zeker niet meer dan een alinea.

🚩 Checkpoint: Beschrijving

Afbeelding gemaakt om de component visueel duidelijk te maken

Doel: De component is visueel duidelijk.

Om de community letterlijk een beeld te geven van de component voegen we een afbeelding toe. Het kernteam maakt deze in het Figma 'Schetsboek'. Zelf kun je een eigen afbeelding maken, huisstijl maakt niet uit.

🚩 Checkpoint: Afbeelding

Aangemaakt als een GitHub Discussion

Doel: Een plek om input te verzamelen.

We gebruiken GitHub 'Discussions' van NL Design System om input te verzamelen.

Start een GitHub Discussion voor de component. Gebruik hierbij de volgende opzet:

Title

{naam-component}

Description

## Naam


{naam-component}


## Beschrijving


{beschrijving-component}


## Ook bekend als


{andere namen die je bent tegengekomen toen je de naam bepaalde, niet verplicht}


## Gerelateerde componenten


{zie hieronder}


## Onderzoek

Gerelateerde componenten

Het kan voorkomen dat andere componenten sterk gerelateerd zijn aan dit component. Denk bijvoorbeeld aan Button en Action group. Dan is het handig om deze componenten naar elkaar te laten verwijzen, indien mogelijk via een link. Noteer gerelateerde componenten als volgt:

## Gerelateerde componenten


X, Y, of Z.

🚩 Checkpoint: Discussion URL

Staat in de publieke backlog van NL Design System

Doel: Zichtbaarheid en overzicht creëren zodat componenten niet dubbel worden toevoegd.

We gebruiken 'Issues' in de GitHub 'Backlog' repository van NL Design System om onze backlog te beheren.

Maak een 'Issue voor de component. Gebruik hierbij de volgende opzet:

Title

{naam-component}

Description

## Naam


{naam-component}


[Link naar GitHub Discussion]({url-github-discussion})
  • Selecteer bij 'Labels' het label: Component.
  • Selecteer bij 'Projects' het project: Components - 1 - Help Wanted.

Tip! Het selecteren van labels en projects kan alleen door het kernteam worden gedaan. Vraag ons gerust even om hulp, kleine moeite.

🚩 Checkpoint: Backlog

Tip: Checkpoints afvinken

Door de vorige stap is de component toegevoegd aan het Help Wanted bord. Je kunt nu de reeds behaalde checkpoints afvinken door per kolom de juiste waarde in te vullen.

Bewijs verzameld dat de component algemeen bruikbaar is

Doel: Alleen componenten die naar verwachting in de Hall of Fame kunnen komen willen we toevoegen als Help Wanted.

Community om hulp vragen

Om meer te leren over de component vragen we de community om hulp. Deze oproep doen we via de GitHub Discussion en Slack.

Oproep via GitHub Discussion

Vul de beschrijving van de GitHub Discussion aan met de onderstaande oproep. Plaats deze boven de informatie die daar al stond zoals Naam, Beschrijving, etc.

  • Voeg de afbeelding toe.
  • Wijzig de 'alt text' die automatisch door GitHub wordt toegevoegd. Bijvoorbeeld:
    • verschillende vormen van een {naam-component} component
    • visuele weergave van een {naam-component} component
  • Voeg onderstaande tekst toe, vul aan waar nodig en 'Update' de GitHub Discussion.
We willen graag meer leren over de {naam-component} component. In welke vorm, of vormen, wordt deze momenteel ingezet en toegepast binnen jouw organisatie?


Deel hieronder een link naar Figma, Storybook, GitHub of screenshots. Met deze informatie kunnen we bewijzen dat de component onderdeel moet worden van de NL Design System component library.


Daarnaast wordt het delen van onderzoek gewaardeerd. Dus heb je zelf onderzoek gedaan en zijn er inzichten voor dit component? Dan horen we dit ook graag!


[Link naar bericht in Slack]({url-slack-bericht})


---

Oproep via Slack

Plaats de oproep in het Slack channel #nl-design-system.

Hey community 👋


We willen graag meer leren over de {naam-component} component. In welke vorm, of vormen, wordt deze momenteel ingezet en toegepast binnen jouw organisatie?


Deel een link naar Figma, Storybook, GitHub of screenshots in de [GitHub Discussion voor de {naam-component} component]({url-github-discussion}), of in een thread onder dit bericht. Met deze informatie kunnen we bewijzen dat de component onderdeel moet worden van de NL Design System component library.


Daarnaast wordt het delen van onderzoek gewaardeerd. Dus heb je zelf onderzoek gedaan en zijn er inzichten voor dit component? Dan horen we dit ook graag!

Vergeet niet de link naar het Slack bericht toe te voegen aan de oproep in de GitHub Discussion.

Zelf op onderzoek uit

Niet elke organisatie zal op de oproep reageren. Ga daarom ook zelf op onderzoek uit. Duik in Figma, Storybook, GitHub en documentatie omgevingen voor een 'Screenshot-Safari 📸'. Maak screenshots van de component, varianten en states. Het gaat om bewijs verzamelen dat de component bestaat en in welke vorm, of vormen, deze wordt toegepast.

  • Kom je de component niet tegen in Figma, Storybook, GitHub of documentatie omgevingen? Dan zou je ook de website van de organisatie kunnen bekijken.
  • Kom je de component maar op 1 plek tegen? Documenteer het nut en noodzaak voor de component met een uitgebreide doelbeschrijving. Gebruikersonderzoek zou je hierbij goed kunnen helpen.

Het kernteam houdt deze set van organisaties aan. Hiermee hebben we een mooie mix te pakken van gemeentes, leveranciers en overige overheidsorganisaties. Zelf kun je deze lijst ook gebruiken, maar gebruik gerust andere bronnen.

Amsterdam

Den Haag

DSO

DUO

Documentatie website

Open Formulieren

Storybook

OpenGemeenten

Gebruik in Patternlab het linkadres van de h2 of h3 om naar een specifiek onderdeel te linken.

Rotterdam

RVO

Utrecht

Bevindingen vastleggen

Voeg per organisatie een losse comment toe aan de GitHub Discussion. Gebruik onderstaande tekst als basis.

## {naam-organisatie}


<!-- Links naar component implementatie (niet verplicht) -->


- [Documentatie website]({url-documentatie-website})
- [Storybook]({url-storybook})
- [Figma]({url-figma})
- [GitHub]({url-github})


---


### Screenshots / Varianten


**{Omgeving}**


{naam-variant}
{Rationale variant}
{Screenshot}


---


### Notities


<!--
- Vul aan waar nodig.
- Laat weg wat niet van toepassing is.
- Noteer wat je opvalt.
  - Zijn er specifieke opties (properties) beschikbaar?
  - Zijn er specifieke design keuzes gemaakt?
  - Is er documentatie beschikbaar?
  - Heeft de component een andere naam?
  - Is er onderzoek beschikbaar?
  - etc.
 -->

🚩 Checkpoint: Bruikbaar

Doel: Er is niet alleen een schets beschikbaar, maar tenminste één uitgewerkte implementatie.

In de stap Bevindingen vastleggen zijn er waarschijnlijk al links beschikbaar. Dan is deze stap al gedaan. Voeg anders een linkje van je eigen implementatie in Figma of Storybook toe in de discussion. Zorg ervoor dat dit linkje te bekijken is zonder in te loggen.

🚩 Checkpoint: Link

Naam en beschrijving van benodigde varianten bepaald

Doel: Alleen varianten die algemeen nut hebben zijn vastgelegd. Daarnaast is het duidelijk waarvoor de variant bedoeld is.

In de stap Bevindingen vastleggen zijn er waarschijnlijk al beschrijvingen van varianten beschikbaar. Dan is deze stap al gedaan.

Noteer anders de naam en beschrijving van de algemeen nuttige varianten. Als je twijfelt over de rationale van een variant kun je de betreffende organisatie eventueel om aanvullende toelichting vragen. Als je twijfelt over het algemeen nut van een variant kun je deze altijd later nog toevoegen.

🚩 Checkpoint: Varianten

Nut van component is onderbouwd door gebruikersonderzoek

Doel: We kunnen aantonen dat dit een component is dat voor eindgebruikers werkt.

Zijn er inzichten rondom de component beschikbaar omdat deze een rol heeft gespeeld bij gebruikersonderzoek? Super! Daarnaast kun je 'desk-research' doen om inzichten en 'best-practices' te verzamelen.

Kijk bijvoorbeeld bij:

Plaats verwijzingen naar onderzoek onderaan in de beschrijving van de GitHub Discussion. Noteer deze als volgt:

## Onderzoek


[Titel - Afzender](url)
Korte beschrijving


[Titel - Afzender](url)
Korte beschrijving


[Titel - Afzender (PDF, 124 kb)](url)
Korte beschrijving

🚩 Checkpoint: Onderzoek

Nut van component is door het kernteam bevestigd

Doel: kernteam verwacht dat dit component tot Hall of Fame kan komen.

Dit is het moment om de component in zijn geheel nog eens af te stemmen met het kernteam. Deel een link naar de GitHub Discussion met het kernteam via Slack. Na akkoord voert het kernteam de laatste stap uit.

Stuur dit bericht naar #nl-design-system op Slack:

Hiep hoi!


Het is zover, de volgende component is helemaal klaar voor een Help Wanted stempel.


Naam: **{naam-component}**
Beschrijving: **{beschrijving-component}**


[GitHub Discussion voor de {naam-component} component]({url-github-discussion})


Er is nog 1 stap over, namelijk: verwachten we dat deze in de Hall of Fame zou kunnen komen? Laat het weten via een emoticon.


🤩 Top, doen! (hetzelfde als niets zeggen).
😭 Nee, deze moet nooit naar de Hall of Fame.
🤨 Ik snap de naam of het nut niet.

Kernteam hakt knoop door

Deze stap kan enkel worden uitgevoerd door het kernteam.

Iedereen mag wat vinden, maar de verschillende specialismes uit het kernteam moeten wat vinden. Dus post een link naar het 'Hiep hoi' bericht in het #nl-design-system-kernteam kanaal. Je kan @here gebruiken om iedereen even wakker te schudden.

Het kernteam bespreekt de component aan het eind van de eerstvolgende 'Weekly'. Eventueel benodigde acties worden ter plekke doorgevoerd of voor een volgende sprint vastgelegd.

Akkoord?

Ga verder bij Status naar Help Wanted.

🚩 Checkpoint: Kernteam = 'Done'

Niet akkoord?

Plaats deze tekst in de 'thread' van het 'Hiep hoi' bericht, vul aan waar nodig.

❌ Het kernteam heeft besloten dat de naam en beschrijving van dit component duidelijk zijn, maar niet voldoende nuttig is voor meerdere organisaties.


Dit hoeft niet te betekenen dat {naam-component} nooit de Help Wanted status krijgt. De [GitHub Discussion voor de {naam-component} component]({url-github-discussion}) blijft beschikbaar voor het delen van voorbeelden, varianten en gebruikersonderzoek.

🚩 Checkpoint: Kernteam = 'Declined'

Status bijgewerkt naar Help Wanted

Doel: iedereen kan zien dat de component nu richting Community wil.

Deze stap kan enkel worden uitgevoerd door het kernteam.

  • Voeg het 'Help Wanted' label toe aan de GitHub Discussion.
  • Voeg het 'Help Wanted' label toe aan het backlog issue.
  • Selecteer bij ‘Projects’ de volgende extra projecten:
    • Components - 2 - Community
    • Components - 3 - Candidate
    • Components - 4 - Hall of Fame
  • Filter het Community bord op de component door op {naam-component} te zoeken.
  • Kopieer de URL na het filteren.
  • Voeg onderstaande tekst toe als comment aan de GitHub Discussion.
## ✨ Dit component is nu Help Wanted ✨


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

🚩 Checkpoint: Status

Vindbaar op de NL Design System website

Doel: Hierdoor kan de component worden opgepakt door de community.

Deze stap kan enkel worden uitgevoerd door het kernteam.

Schematische afbeelding maken

Branch klaar zetten

  • Open de documentatie repository in Visual Studio Code.
  • Maak een nieuwe branch aan. Gebruik hiervoor de volgende naam:

Branch

feat/add-documentation-page-for-{naam-component}

Schematische afbeelding bewerken en toevoegen

Doorloop de volgende stappen om de schematische afbeelding mee te laten kleuren met de statussen van het Estafettemodel.

Tip! Installeer in Visual Studio Code de extentie 'SVG' ontwikkeld door Jock.

  • Ga naar de folder 'static/svg'.
  • Sleep het SVG-bestand in deze folder. De code van het SVG-bestand wordt zichtbaar.
  • Kies 'View' in de hoofdnavigatie van Visual Studio Code en open 'Command Palette...'.
  • Typ 'svg' en kies voor 'Preview SVG'. De visuele weergave van het SVG-bestand wordt vervolgens zichtbaar.
  • Verwissel alle kleurwaardes van de fills en strokes naar design tokens die zijn aangevuld met een fallback.
    • #F9F6F3 wordt var(--component-illustration-background-color, white).
    • #E4EBED wordt var(--component-illustration-grid-color, #EEE).
    • #004152 wordt var(--component-illustration-color, #666).
    • white wordt var(--component-illustration-background-color, white).

Tip! Met de toetscombinatie Cmd+D (of Ctrl+D) kun je stukjes code selecteren die overeenkomen met je huidige selectie.

  • Voeg de volgende stukjes code toe om het SVG-bestand dynamisch in te laden.
    • Op de 2e regel, direct na <svg..., plak je <symbol id="component-illustration">.
    • Op de voorlaatste regel, vlak voor </svg>, plak je </symbol>.
    • Direct daaronder, ook weer vlak voor </svg>, plak je <use href="#component-illustration"/>.
  • Maak een commit en gebruik hierbij het volgende bericht:

Commit Message

feat: add illustration for {naam-component}

Documentatie pagina toevoegen

  • Ga naar de folder 'docs/componenten'.
  • Voeg een nieuwe folder toe voor de component en gebruik hiervoor kebab-case als schrijfwijze.
  • Maak een nieuw bestand aan en noem het 'index.mdx'.
  • Vul het bestand in volgens de component template.
  • Maak een commit en gebruik hierbij het volgende bericht:

Commit Message

feat: add documentation page for {naam-component}

Component progress bijwerken

  • Publiceer een nieuwe versie van het component-progress package door op Run Workflow te klikken in GitHub Actions van de Index repository. Kies hierbij voor de main branch.
  • Wacht tot component-progress op npm is bijgewerkt. Je kunt dit controleren door te kijken naar de datum bij Last publish.
  • 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 commit en gebruik hierbij het volgende bericht:

Commit Message

build: update component progress

Branch publiceren

  • 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

docs: add {naam-component} to documentation site

Description

- add illustration for {naam-component}.
- add documentation page for {naam-component}.
- update component progress.
  • Klik op 'Create Pull Request'.
  • Geef een developer uit het kernteam via Slack een seintje dat de PR klaar staat.

🚩 Checkpoint: nldesignsystem.nl

🏁 Finish

Zo wat een werk! Je hebt alle stappen genomen en zo alle checkpoints behaald die nodig zijn voor de 'Help Wanted' status van het Estafettemodel. De component gaat nu door voor de 'Community' status. Het is goed om dit ook met de rest van de community te delen.

Plaats deze tekst in de 'thread' van het 'Hiep hoi' bericht, vul aan waar nodig.

✅ Het kernteam heeft besloten dat de naam en beschrijving van dit component duidelijk zijn en de component algemeen nuttig is voor meerdere organisaties.


✨ **Dit component is nu Help Wanted** ✨


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


De [GitHub Discussion voor de {naam-component} component]({url-github-discussion}) blijft beschikbaar voor het delen van voorbeelden, varianten en gebruikersonderzoek.