Figma migratie-stappenplan
Over dit migratie-stappenplan
Dit migratie-stappenplan noemen we ook wel de 'Big Bieb Sync'. Zoals aangegeven is er zoveel veranderd dat een verse installatie sneller is dan alles aan jouw kant stap voor stap aanpassen. Met dit stappenplan helpen we je stap voor stap te migreren.
Het migratie-stappenplan lijkt grotendeels op het algemene Figma stappenplan, maar is uitgebreid met extra uitleg voor iedereen die al eerder met Figma bibliotheken en Tokens Studio heeft gewerkt.
Onderaan deze pagina vind je extra secties voor migratie waarbij we met je meedenken over de volgende vraagstukken:
- Wat doe ik met mijn huidige bibliotheken?
- Wat doe ik met mijn lokale bibliotheek?
- Wat doe ik met mijn prototypes?
Op naar 'Doel 3' en voorbereiding
In het algemene stappenplan spreken we over 3 doelen. Men kan stoppen zodra het eigen doel is behaald.
- Snel een prototype maken met componenten op basis van het Start-thema.
- Voor een langere periode met componenten werken op basis van het Start-thema.
- Voor een langere periode met componenten werken op basis van een eigen thema.
Elk doel bouwt voort op het vorige. We geven steeds aan wanneer je een doel hebt behaald, zodat je weet wanneer je verder kunt, of juist klaar bent.
Voor een complete migratie met een eigen thema zal je doel 3 willen behalen.
Voordat je begint, is het slim om de volgende documentatie te hebben gelezen:
Loop je ergens vast? Geen zorgen. Neem contact op met het kernteam en we denken graag met je mee.
OK. Aan de slag!
Figma bibliotheken
Voor de migratie plaats je de nieuwe bibliotheken naast je huidige bibliotheken.
Maak een Figma project aan
We adviseren je om binnen Figma een apart ‘Project’ voor je Design System aan te maken. Zo houd je een duidelijke scheiding tussen je Design System en overige design bestanden.
Meer informatie over Figma bestanden en projecten
Meer informatie over Figma kun je vinden op help.figma.com en forum.figma.com.
Figma bibliotheken dupliceren
De Figma bibliotheken zijn Open Source beschikbaar en te bereiken via Figma Community.
🎥 Video: Bibliotheken dupliceren
- Ga naar de Figma Community profielpagina van NL Design System.
- Klik op 'NL Design System - Bibliotheek'.
- Klik op 'Open'.
Het duplicaat staat nu in je 'Drafts'. Verplaats de bibliotheek naar het Figma project dat je hebt aangemaakt.
- Klik op het chevron icoon naast de naam van 'NL Design System - Bibliotheek (Community)'.
- Kies voor 'Move file...'.
- Selecteer de gewenste locatie.
Herhaal deze stappen voor de 'NL Design System - ToDo Bibliotheek'.
Om duidelijk te maken dat deze bestanden nu binnen jouw organisatie staan, pas je de naam aan.
- Hernoem
NL Design System - Bibliotheek (Community)naarNL Design System - Bibliotheek - {naam-organisatie}. - Hernoem
NL Design System - ToDo Bibliotheek (Community)naarNL Design System - ToDo Bibliotheek - {naam-organisatie}.
Figma bibliotheken publiceren
De Figma bestanden zijn nog geen bibliotheken. Om er bibliotheken van te maken die je vanuit andere bestanden kan aanroepen, moeten ze worden gepubliceerd.
🎥 Video: Bibliotheken publiceren
- Klik op 'Assets'.
- Klik op 'Publish...'.
Herhaal deze stappen voor de NL Design System - ToDo Bibliotheek.
Figma bibliotheken koppelen
Nadat de bestanden zijn gepubliceerd, moeten ze aan elkaar worden gekoppeld. Hierdoor wordt de connectie tussen componenten uit beide bibliotheken hersteld.
🎥 Video: Bibliotheken koppelen
- Ga binnen
NL Design System - Bibliotheek - {naam-organisatie}naar Assets. - Klik op 'Add more libraries'.
- Zoek of browse naar de
NL Design System - ToDo Bibliotheek - {naam-organisatie}. - Klik op 'Add to file'.
Herhaal deze stappen, maar dan gezien vanuit de NL Design System - ToDo Bibliotheek.
Helaas komt het voor dat componenten ondanks het koppelen toch hun connectie met de andere bibliotheek verliezen. Daarom is het verstandig om dit te controleren.
- Ga binnen
NL Design System - Bibliotheek - {naam-organisatie}naar Assets. - Klik op het boek icoon.
- Klik op 'View missing libraries'.
- Kies voor
NL Design System - ToDo Bibliotheek - {naam-organisatie}. - Klik op 'Swap library'.
Herhaal deze stappen, maar dan gezien vanuit de NL Design System - ToDo Bibliotheek.
Figma bibliotheken gebruiken
Nu kun je de bibliotheken gebruiken voor het maken van prototypes. Hiervoor moet je de bibliotheken koppelen aan een Figma bestand.
🎥 Video: Bibliotheken gebruiken
- Maak een nieuw bestand aan.
- Maak een eerste Frame aan.
- Klik op 'Browse team libraries'.
- Zoek op 'nl design system'. De bibliotheken verschijnen vanzelf.
- Klik op 'Add to file' voor de
NL Design System - Bibliotheek - {naam-organisatie}. - Klik op 'Add to file' voor de
NL Design System - ToDo Bibliotheek - {naam-organisatie}.
Nu kun je componenten uit beide bibliotheken gebruiken voor het maken van een prototype.
Doel 1 behaald 🎉
Je kunt nu stoppen als je doel was om snel een prototype te maken met componenten op basis van het Start-thema. Wil je voor een langere periode met deze componenten werken? Ga dan verder met het stappenplan.
Tokens Studio
Design tokens staan buiten Figma opgeslagen in een JSON bestand. Of je nu het Start-thema blijft gebruiken of een eigen thema wilt doorvoeren: je wilt een connectie leggen met de design tokens. Dat doe je door gebruik te maken van Tokens Studio plugin.
De plugin wordt regelmatig bijgewerkt. Hierdoor kunnen onderstaande stappen, video's en screenshots verouderd raken. Voor de meest up-to-date documentatie van de plugin ga je naar docs.tokens.studio.
- Wil je enkel van het Start-thema gebruik maken? Vervolg dan het stappenplan.
- Wil je een eigen thema doorvoeren? Ga dan verder bij 'Zelf een thema doorvoeren'.
Voor de migratie ga je verder bij 'Zelf een thema doorvoeren'.
Tokens Studio gebruiken voor het Start-thema
🎥 Video: Tokens Studio gebruiken voor het Start-thema
- Open
NL Design System - Bibliotheek - {naam-organisatie}. - Klik op 'Actions' (Cmd+K).
- Zoek op 'Tokens Studio'.
- Open 'Tokens Studio'.
Het introductiescherm kan er anders uitzien, maar zorg ervoor dat je bij het tabblad ‘Settings’ terechtkomt.
- Klik op 'Add new sync provider'.
- Kies voor 'URL'.
- Vul een naam in. Bijvoorbeeld:
Start-thema. - Vul de volgende URL in:
https://raw.githubusercontent.com/nl-design-system/themes/refs/heads/main/packages/start-design-tokens/figma/start.tokens.json
- Klik op 'Save'.
- Klik vervolgens op de tab ‘Tokens’ en... voilà! Daar zal je de tokens hebben.
- Vink de checkboxes 'brand', 'common' en 'components' aan.
De design tokens van het Start-thema zijn nu gekoppeld aan de Figma bibliotheek.
Herhaal deze stappen, maar dan gezien vanuit de NL Design System - ToDo Bibliotheek.
Wil je het Voorbeeld-thema inladen? Dat kan! Vul dan de volgende URL in bij ‘Sync provider’:
codevoorbeeldhttps://raw.githubusercontent.com/nl-design-system/themes/refs/heads/main/packages/voorbeeld-design-tokens/figma/voorbeeld.tokens.json
🎥 Video: Tokens Studio gebruiken voor het Voorbeeld-thema
Updates
Het kernteam zit natuurlijk niet stil. We voeren geregeld updates door in de Figma bibliotheken én het JSON bestand met design tokens. Omdat je via een URL gekoppeld bent aan het JSON bestand, ben je automatisch up-to-date. Je kunt de Figma bibliotheken 'in sync' houden door de updates die wij doen, ook aan jouw kant door te voeren.
Op de pagina 'Figma changelog' zie je welke updates zijn doorgevoerd. Wanneer je deze updates doorvoert, bepaal je helemaal zelf. We raden wel aan om dit met enige regelmaat te doen, zodat je zeker weet dat je met de nieuwste versies werkt.
We sturen eens in de 2 maanden een reminder via Slack in het #nl-design-system-designers kanaal.
Doel 2 behaald 🎉
Je kunt nu stoppen als je doel was om voor een langere periode met componenten te werken op basis van het Start-thema.
Vervolg het stappenplan als je een eigen thema wilt doorvoeren.
Zelf een thema doorvoeren
Als je een eigen thema wilt doorvoeren, ga je werken met GitHub en Tokens Studio. GitHub gebruik je om het JSON-bestand met design tokens op te slaan. Met de Tokens Studio plugin importeer, bewerk en exporteer je tokens in Figma.
Bij elke stap vind je een video waarin we laten zien hoe we een thema doorvoeren voor de fictieve 'gemeente Voorbeeld'.
Laten we beginnen aan de kant van GitHub.
Eerlijk is eerlijk. Als je niet bekend bent met GitHub kunnen de volgende stappen lastig zijn. Loop je vast? Vraag dan een developer uit je team om hulp, of neem contact op met het kernteam.
GitHub account aanmaken
Maak een account aan bij github.com.
GitHub Repository
Een repository kan je zien als de hoofdmap van je project. Binnen deze repository plaats je het JSON bestand met design tokens.
Afhankelijk van de situatie van jouw organisatie zal worden bepaald waar het JSON bestand moet komen staan.
Situatie A
Jouw organisatie heeft al een map met design tokens binnen de NL Design System 'themes repository'.
- Controleer wanneer de laatste wijziging op de design tokens heeft plaatsgevonden.
- Bekijk wie deze wijzigingen heeft gedaan.
Zijn de wijzigingen recent? En ken je de persoon die ze heeft gedaan? Stem dan even met elkaar af. Kom je er niet uit? Stel je vraag gerust in Slack.
Situatie B
Jouw organisatie heeft nog géén map binnen de NL Design System 'themes repository'. En dat wil je wel.
Neem contact op met het kernteam.
Situatie C
Jouw organisatie werkt vanuit een eigen GitHub omgeving.
- Stem met je developers af waar de design tokens geplaatst kunnen worden.
- Hulp nodig? Neem contact op met het kernteam.
Inhoud JSON met Start-thema kopiëren
De Figma bibliotheken maken gebruik van het Start-thema. Het JSON bestand dat hierbij hoort staat in GitHub.
- Bekijk het JSON bestand met het Start-thema.
- Klik op 'Copy raw file'.
JSON bestand aanmaken
Voor de migratie plaats je het nieuwe JSON bestand naast het huidige JSON bestand.
🎥 Video: JSON bestand aanmaken
- Ga naar de locatie waar het JSON bestand moet komen staan.
- Klik op 'Add file'. Je vindt deze functie rechtsboven.
- Kies voor 'Create new file'.
- Geef het bestand een naam. Bijvoorbeeld:
{naam-organisatie}.tokens.json. - Plak de inhoud van het JSON bestand met het Start-thema.
- Klik op 'Commit changes'.
- Als commit message kun je noteren:
json met design tokens toegevoegd. - Als branch kun je noteren:
add-tokens-json - Klik op 'Propose changes'.
- Klik op 'Create pull request'.
- Geef development een seintje en zorg dat je pull request wordt goedgekeurd.
Voor situatie A en B is dit een developer uit het kernteam. Neem contact op met het kernteam.
Voor situatie C is dit een developer van je eigen organisatie.
Personal access token aanmaken
Ondanks de naam heeft een personal access token niets met design tokens te maken. Je hebt een personal access token nodig met de benodigde rechten om via Tokens Studio design tokens te kunnen importeren, bewerken én exporteren.
🎥 Video: Personal access token aanmaken
- Ga naar github.com/settings/tokens.
- Klik op 'Generate new token'.
Vul de gegevens in
- Token name: Deze wordt enkel gebruikt voor GitHub zelf. Hier mag je van maken wat je wilt. Bijvoorbeeld:
Tokens van {naam-organisatie}. - Resource owner: Staan je tokens in de NL Design System 'themes repository'? Kies dan voor 'nl-design-system'. Staan de tokens in de GitHub omgeving van jouw organisatie? Selecteer deze dan als resource owner.
- Expiration: Bepaal wanneer je personal access token zou moeten verlopen. Bijvoorbeeld na een half jaar. Je krijgt vanzelf een email wanneer deze datum in zicht komt.
- Kies bij 'Repository access' voor 'Only select repositories'.
- Selecteer de repository waar de tokens van jouw organisatie staan.
- Klik onder 'Permissions' op 'Repository permissions'.
- Kies bij 'Contents' voor 'Access: Read and write'.
Genereren en noteren
- Klik op 'Generate token'.
- Kopieer je personal access token.
- Bewaar je personal access token op een veilige plek waar je hem ook altijd terug kan vinden.
Let op!
Deel je token nooit met iemand die geen toegang zou moeten hebben tot je repository. Behandel de token als je persoonlijke wachtwoord.
Tokens Studio activeren
Nu je in GitHub alles hebt klaargezet, kunnen we in Figma via Tokens Studio een connectie leggen met de design tokens.
🎥 Video: Tokens Studio activeren
- Open
NL Design System - Bibliotheek - {naam-organisatie}. - Klik op 'Actions' (Cmd+K).
- Zoek op 'Tokens Studio'.
- Activeer Tokens Studio.
Het introductiescherm kan verschillen.
Zie je een knop met de tekst 'Enter credentials' staan? Ga dan verder bij 'Tokens Studio koppelen aan JSON'.
Zie je een knop met de tekst 'New empty file' staan?
- Klik op die knop.
- Ga binnen Tokens Studio naar het tabblad 'Settings'.
- Klik op 'Add new sync provider'.
- Kies voor 'GitHub'.
- Nu kun je de 'Credentials' gaan invullen.
Tokens Studio koppelen aan JSON
Er staan standaard al gegevens ingevuld. Dat is prima. We passen aan wat nodig is.
Name
Deze naam wordt enkel gebruikt voor de plugin zelf. Hier mag je van maken wat je wilt. Bijvoorbeeld: {naam-organisatie} thema.
Personal access token
Vul je personal access token in.
Repository
Als jouw JSON bestand in de Themes repository van NL Design System staat, kun je laten staan wat er nu staat: nl-design-system/themes.
Staat het JSON bestand in een repository binnen de GitHub omgeving van jouw organisatie? Vul dan de gegevens van deze repository in.
Branch
Hier kun je main laten staan.
Token Storage location
Je kunt dit zien als het pad naar het JSON bestand binnen een repository. Dit pad kan per situatie verschillen.
Het makkelijkst is om in GitHub naar je JSON bestand te gaan. Boven het bestand zie je een kruimelpad. Achter het kruimelpad vind je een functionaliteit om het pad te kopiëren. Gebruik die om het pad eenvoudig over te nemen.
Base URL
Dit is optioneel. Hier hoef je niets mee te doen.
Opslaan
- Klik op 'Save'.
- De plugin zal aangeven dat er al tokens in de opgegeven ‘repo’ staan en vragen of je deze wilt binnenhalen.
- Klik op ‘Yes’.
Design tokens bekijken
🎥 Video: Design tokens bekijken
- Klik op het tabblad ‘Tokens’ en... Voila! Daar zul je de tokens hebben.
- Zet de checkboxes voor 'brand', 'common' en 'components' aan.
De termen Brand, Common en Component vind je ook terug in de naamgeving van het pagina overzicht van Figma.
Zoals aangegeven bevatten de Figma bibliotheken het Start-thema. Voor deze 'stijl' zijn er al bepaalde waardes ingevuld voor typografie, kleur, spacing, etc. Deze waardes zijn 'hardcoded', oftewel direct ingevuld binnen de set van Basis-tokens die je vindt op het Common niveau.
Een prima 'Startpunt', maar jij wilt de huisstijl van jouw organisatie als thema doorvoeren.
Omdat huisstijlen verschillen, verschillen ook de vervolgstappen. In plaats van dat we alle mogelijkheden uitschrijven, begeleiden we je via video’s stap voor stap terwijl we als voorbeeld de huisstijl van gemeente Voorbeeld toepassen.
Uiteraard is het ook slim om de documentatie van de Tokens Studio plugin bij de hand te houden. Deze vind je op docs.tokens.studio.
Brand tokens aanmaken
Je kunt de huisstijl-opties van jouw organisatie direct doorvoeren als waarde op het Common niveau. Maar je kunt ook eerst Brand tokens aanmaken, en daar vervolgens vanuit het Common niveau naar verwijzen. Laten we daarmee beginnen.
In deze video bekijken we de huisstijl-opties van gemeente Voorbeeld en laten we zien hoe je hiervoor Brand tokens aanmaakt in Tokens Studio.
🎥 Video: Brand tokens aanmaken
Als je migreert, heb je eerder Brand tokens voor jouw organisatie vastgelegd in Tokens Studio. Het is niet nodig om al die Brand tokens opnieuw aan te maken.
- Open Tokens Studio in een ander bestand, zodat je je 'oude' JSON kunt bekijken.
- Maak de afweging welke Brand tokens je nodig hebt voor jouw organisatie.
- Kopieer en plak deze Brand tokens vervolgens naar de 'brand' set in de nieuwe JSON.
Omdat het Start-thema vrij algemene waardes bevat binnen de basis-tokens, is de kans groot dat je met kleur en typografie tokens al voldoende hebt. Daarnaast is het goed om te weten dat je huisstijl-opties ook direct op het Common niveau kunt doorvoeren. Verderop in het stappenplan lees je daar meer over.
Naar Brand tokens verwijzen
Nadat je Brand tokens hebt aangemaakt, kun je hier naar gaan verwijzen vanuit het Common niveau. In deze video laten we zien hoe je dat doet.
🎥 Video: Naar Brand tokens verwijzen - deel 1
Het instellen van de kleuren kost even wat tijd, maar daarna heb je er geen omkijken meer naar. Het kleurcontrast staat dan al goed ingesteld op het Common niveau, waardoor je hier bij het ontwerpen of ontwikkelen van nieuwe componenten geen extra werk aan hebt. Heeft jouw organisatie voor bepaalde onderdelen geen eigen richtlijnen? Dan kun je gerust de waarden uit het Start-thema laten staan.
In de volgende video zien we het resultaat van het verwijzen naar Brand tokens.