Hier kun je informatie vinden over algemene richtlijnen, gebruikersonderzoek, patronen etc.
We zijn nog druk bezig deze informatie aan te vullen en te verbeteren. Heb je nog documentatie of gebruikersonderzoek die we misschien kunnen gebruiken? Laat het ons dan weten.
Voor de documentatie gebruiken we Markdown bestanden die we met in GitHub opslaan. Hierdoor hebben we een bestandsformaat dat door vele verschillende producten ondersteund wordt en een plek waar we met versionering en reviews samen kunnen werken. Om met al deze documentatie een website te maken gebruiken we Docusaurus.
Fijn als je hier toevoegingen of verbeteringen aan bij wil dragen. Als je dat in Markdown kan doen is dat voor ons het allerhandigst. Hieronder een aantal manieren waarop bijdragen voorgesteld kunnen worden.
Note: We zijn blij met iedere bijdrage, dat betekent niet dat alle bijdrages 1-op-1 worden overgenomen in het NL Design System. Soms hebben wij een andere visie, of moet de reden waarom de richtlijn wordt voorgesteld nog beter verscherpt of verduidelijkt worden voordat het als richtlijn in NL Design System opgenomen wordt.
In GitHub kun je gemakkelijk een los Markdown bestand maken met Gist, mits je een GitHub account hebt. Heb je een document dat je wil bijdragen, stuur ons dan een linkje naar die gist.
fork
knop te drukkenWe gebruiken pnpm
om afhankelijkheden te installeren en de website met Docusaurus te draaien. Zorg dat je dat eerst installeert, dat kan bijvoorbeeld met npm
.
Als je hier hulp bij nodig hebt kun je ons op Slack vinden of even een e-mail sturen
pnpm install
om te zorgen dat alle afhankelijkheden die Docusaurus nodig heeft beschikbaar zijnpnpm run build
om de CSS te builden (dit hoeft alleen de eerste keer)pnpm run start
om Docusaurus te starten.Docusaurus website is running at http://localhost:3000/
met Cmd
ingedrukt kun je deze link aanklikkenOm documenten aan te passen kun je de folder openen in een code editor naar keuze. Wij gebruiken in het kernteam bijvoorbeeld VSCode of de simpelere Sublime. Als je alleen markdown will aanpassen kun je ook kiezen om een los bestand aan te passen of aan te maken en een markdown editor te gebruiken zoals iA Writer
Zolang je het script in je terminal hebt draaien zal de website automatisch de opgeslagen documentatie veranderingen laten zien. Als je de website structuur hebt aangepast dan is het nodig de website eerst te stoppen en dan opnieuw op te starten.
Cmd+C
in te typen in de terminal waar het script draait.pnpm run start
et voilá, de veranderingen worden zichtbaar.Apache HTTP server wordt momenteel gebruikt voor hosting van nldesignsystem.nl. Als je Docker en docker-compose
geïnstalleerd hebt, dan kun je de website starten met Apache, zodat je lokale testomgeving nauwkeuriger lijkt op productie.
Het belangrijkste voordeel is dat je HTTP redirects kunt testen die in static/.htaccess
zijn ingesteld.
pnpm run build
docker-compose up
http://localhost:8080/
static/.htaccess
aanpassen, en gelijk de resultaten testen.pnpm run build
na elke wijziging en pnpm run serve
pnpm run build
eenmalig, daarna pnpm run start
pnpm run test-e2e
pnpm run serve:test-report
Gebaseerd op de blog post van Docusaurus Upgrading frontend dependencies with confidence gebruiken we Playwright met Argos CI voor visuele regressie-tests van de website nldesignsystem.nl.
Voeg het label visual regression test
toe aan je pull request om Argos CI aan het werk te zetten. We hebben 5,000 screenshots per maand, verspil geen screenshots als je pull request nog niet klaar is.