Hyvä UI als design system in Figma: opzet en handoff naar code

De meeste vertraging in een frontend-traject zit niet in het bouwen, maar in de rondes erna: spacing klopt net niet, een state is vergeten, een component in Figma bestaat niet in code. Hyvä UI pakt dat aan met een Figma-bestand dat dezelfde componenten bevat als de bibliotheek. Dit artikel laat zien wat er in dat bestand zit, hoe je het inricht voor een merk, hoe je de koppeling met code legt en welke afspraken nodig zijn om de handoff echt soepel te maken.

Wat Hyvä UI is en wat de licentie kost, lees je in Wat is Hyvä UI?.

Wat zit er in het Hyvä UI Figma-bestand?

Het Figma-bestand hoort bij de Hyvä UI-licentie en staat op het Hyvä-profiel in Figma. Het is opgezet als design system:

• Styles voor tekst, kleur en effecten. Pas je een style aan, dan verandert die overal in de bibliotheek.
• Componenten met Auto Layout, zodat ze meeschalen met inhoud en schermbreedte.
• Shared components en varianten. Wijzig je het hoofdcomponent, dan volgen alle instanties.

De componenten volgen de bibliotheek in code: headers en menu's, minicart, product cards met swatches, galerijen, filters, modals en popups, footers, banners, USP-blokken en meer. Daardoor ontwerpt de designer met bouwstenen die al bestaan, in plaats van dingen te tekenen die daarna van nul gebouwd moeten worden.

Vragen over het bestand kun je stellen in het #hyva-ui-figma-kanaal in de Hyvä Slack.

Het bestand inrichten als bibliotheek

De werkwijze die Hyvä zelf beschrijft, in vier stappen:

1. Aanpassen. Zet de kleur-, tekst- en effect-styles om naar de huisstijl. De componenten die die styles gebruiken, veranderen mee.
2. Publiceren. Open de Library-modal (via de toolbar, het Assets-paneel of Alt/⌥ + 3) en kies Publish. Je bepaalt zelf welke componenten je meepubliceert. De eerste keer kan dat even duren.
3. Activeren in projectbestanden. Activeer in andere Figma-bestanden de gepubliceerde Hyvä UI-library. Componenten en styles zijn dan beschikbaar via het Assets-paneel.
4. Onderhouden. Wijzigingen in de library publiceer je opnieuw; projectbestanden kunnen de updates overnemen.

Zo heb je één bronbestand per merk en meerdere schermontwerpen die daaruit putten.

Tokens: de brug tussen Figma en code

Styles in Figma en tokens in je theme zijn twee plekken met dezelfde waarden. Ze lopen alleen gelijk als je dat organiseert.

Werk in lagen

1. Primitieven: ruwe waarden, zoals blue-700 of een 4px-spacingschaal.
2. Semantische tokens: betekenis, zoals color-primary, color-danger, color-surface.
3. Component-tokens (optioneel): button-padding-x, input-border-color.

De designer past bij een nieuw merk de semantische laag aan; het team doet hetzelfde in de theme-config. Beide wijzigingen zijn klein en voorspelbaar.

Gebruik dezelfde namen

Spreek af dat een kleur in Figma dezelfde naam heeft als in de theme-config. Heet hij primary/600 in Figma, dan is het primary-600 in code en bg-primary-600 in de template. Dat is een afspraak die je maakt, geen automatisme: het Hyvä UI Figma-bestand werkt met styles, en de namen in je theme kies je zelf.

Een vereenvoudigd voorbeeld met tokens in hyva.config.json (Hyvä 1.4 en nieuwer):

{
  "tokens": {
    "values": {
      "color": {
        "primary": {
          "50": "#f0f9ff",
          "600": "#0284c7",
          "700": "#0369a1"
        },
        "surface": {
          "DEFAULT": "#ffffff",
          "muted": "#f8fafc"
        }
      }
    }
  }
}

In oudere themes op Tailwind v3 staat hetzelfde in theme.extend.colors van tailwind.config.js.

Van Figma naar code zonder overtikken

Met een plugin als Tokens Studio exporteer je tokens uit Figma als JSON. Hyvä zet die met npx hyva-tokens om naar CSS-variabelen voor Tailwind; je verwijst er in hyva.config.json naar met tokens.src. De details, inclusief de verschillen tussen DTCG en het oudere exportformaat, staan in design tokens koppelen aan Tailwind.

Het klassieke handoff-probleem

Een designer tekent een modal: varianten, vier states, precieze spacing. Het team bouwt hem in code met andere namen, een andere spacinglogica en andere breakpoints. Daarna volgen review, feedback, aanpassing en nog een review.

Dat is geen mensenfout maar een structuurprobleem. Figma en code spreken een andere taal, tenzij je ze koppelt via gedeelde componenten en tokens.

Hoe Hyvä UI de kloof kleiner maakt

1. Dezelfde componenten aan beide kanten. Zegt de designer "Minicart, variant popover", dan weet het team precies welk component in code dat is. Geen vertaalslag.

2. Waarden liggen vast. Kleuren, spacing en radius komen uit dezelfde set. Wat de designer kiest, is wat er in de template als class staat.

3. Gedrag ligt vast. Een accordion of mobiel menu uit Hyvä UI werkt op een vaste manier. De vraag "hoe moet dit openklappen?" hoeft niet meer gesteld te worden.

Hoeveel tijd dat scheelt, verschilt per team en project. Het effect zit vooral in de eerste correctierondes: die gaan niet meer over details die al vastliggen.

Wat je nodig hebt om het te laten werken

Tooling

De bibliotheek in code haal je op via Composer als dev-dependency, of je downloadt hem via het Hyvä Portal:

composer require --dev hyva-themes/hyva-ui

Daarna kopieer je per component de template naar je theme, volgens de README.md in de map van dat component. Kopieer niet de hele bibliotheek: dan wordt je CSS onnodig groot en kan een update onverwachte gevolgen hebben.

Afspraken

De tool lost het probleem niet op als het proces er niet achter zit. Afspraken die wij hanteren:

• Voor standaard-UI gebruikt de designer alleen componenten uit de Hyvä UI-library.
• Afwijkingen van een component worden in Figma gemarkeerd met een comment, met de reden erbij.
• Nieuwe componenten krijgen eerst een plek in de Figma-library en in code tegelijk, met dezelfde naam. Nooit alleen in één van beide.
• Geen losse CSS op Hyvä UI-componenten zonder overleg; afwijkingen lopen via tokens of classes in de template.
• Tokenwijzigingen gaan via een pull request, net als code.

Zonder die afspraken ontstaat alsnog drift tussen Figma en code.

Wat het vraagt van de designer

• Kleuren vastleggen als style- of tokennaam, niet als losse hex-waarde
• Spacing uitdrukken in stappen van een vaste schaal, bijvoorbeeld een 4px-grid
• States expliciet ontwerpen: hover, focus, disabled, error, loading
• Componenten hergebruiken in plaats van opnieuw tekenen

Dat is geen extra werk, het is precisiewerk dat herhaalwerk voorkomt. Wie Material Design of Carbon kent, herkent de werkwijze.

Stappenplan voor een nieuw project

1. Start met het Hyvä UI Figma-bestand als basis.
2. Pas de semantische styles aan naar het merk en publiceer de library.
3. Leg dezelfde waarden vast als tokens in de theme-config, met dezelfde namen.
4. Ontwerp schermen met componenten uit de library; documenteer afwijkingen met comments.
5. Het team kopieert de bijbehorende Hyvä UI-templates en past ze aan.
6. Review aan de hand van de componentstates in Figma.
7. Wijzigingen daarna altijd aan beide kanten tegelijk doorvoeren.

Performance als bijkomend voordeel

Omdat de componenten in code HTML-first zijn, met Tailwind voor stijl en Alpine.js alleen waar interactie nodig is, laadt wat de designer ontwerpt zonder zware JavaScript-bundle. Geen RequireJS, geen jQuery, geen Knockout in de componentlaag. Voor teams die naast handoff-problemen ook snelheidsklachten hebben, is dat mooi meegenomen. Meet het effect wel op je eigen winkel, met echte gebruikersdata.

Wanneer dit niet de juiste aanpak is

• Eén persoon doet design en bouw. Dan bestaat het handoff-probleem nauwelijks; de Figma-library is dan vooral handig als visuele referentie.
• Je hebt al een volwassen design system. Twee systemen naast elkaar werkt averechts. Koppel je bestaande systeem aan je theme-tokens.
• Je frontend is React of Vue. Hyvä UI levert Magento-templates met Alpine; dat past niet in een React-app.
• Je team gebruikt geen Figma. Dan mis je dit deel van de waarde en is Hyvä UI vooral een componentbibliotheek in code.
• Je project heeft maar een paar componenten nodig. Dan is een library inrichten overhead.
• Je wilt een volledige Magento-frontend vervangen. Dan begin je bij een Hyvä theme; Hyvä UI komt daar bovenop.

En het is geen oplossing voor een slecht designproces. Faalt de overdracht door ontbrekende specificaties of onduidelijke communicatie, dan lost een gedeelde library dat niet vanzelf op.

Het werkt het best als:

• Design en bouw aparte rollen zijn
• Je meerdere Magento-projecten per jaar doet op dezelfde stack
• Je bereid bent de Figma-library te onderhouden naast de code

Licentie

Het Figma-bestand zit bij de Hyvä UI-licentie: eenmalig 250 euro per Magento-installatie, inclusief updates. Hyvä UI zit ook in Hyvä Commerce, en wie vóór 10 november 2025 een betaalde Hyvä Theme-licentie had, houdt toegang. Meer over de componentbibliotheek zelf staat op /hyva-ui.

Hoe wij handoffs aanpakken bij coding.nl

Wij werken als klein vast team zonder projectmanagers, dus een efficiënte overdracht is geen luxe maar een voorwaarde. Bij projecten met een aparte designer stellen we eerst één vraag: werkt de designer al met de Hyvä UI-library? Zo niet, dan beginnen we daar. Niet omdat het verplicht is, maar omdat het voorkomt dat een groot deel van de bouwtijd opgaat aan rondes over spacing en gedrag.

Het echte voordeel van een gedeeld design system is niet de tool zelf, maar de gedeelde taal die het oplevert. De designer weet wat er kan, het team weet wat er verwacht wordt.

Wil je weten of jullie designproces en theme klaar zijn voor deze werkwijze? Wij kijken graag mee in een korte Tech Check: naar je Figma-opzet, je tokens en je theme. Geen sales, gewoon een eerlijk advies. Neem contact op via /contact.