Hyvä UI installeren en configureren

Hyvä UI installeren en configureren

Eén licentie, ~250 euro, geen abonnement. Hyvä UI geeft je een complete componentbibliotheek gebouwd op Tailwind CSS en Alpine.js die je in een middag operationeel hebt. Deze gids laat zien hoe je installeert, Tailwind koppelt en je eerste component rendert.

Wat is Hyvä UI precies?

Hyvä UI is het officiële design system en de componentbibliotheek van Hyvä. Gebouwd op Tailwind CSS en Alpine.js. HTML-first, minimale JavaScript.

Het is geen Hyvä theme. Een Hyvä theme vervangt de volledige Magento 2 frontend — weg met RequireJS, jQuery en Knockout. Hyvä UI is een losse componentbibliotheek. Je gebruikt hem bovenop een Hyvä theme, maar ook in Laravel, headless setups of statische sites.

Framework-agnostisch is hier geen marketingterm. Wij hebben Hyvä UI ingezet in zowel Magento 2 als Laravel-projecten zonder aanpassingen aan de library zelf.

Wat er in de box zit:

• Buttons, forms, modals en dropdowns
• Accordions, tabs en navigatiecomponenten
• Product cards en checkout-patronen
• Een Figma Community-bestand met design tokens die 1-op-1 matchen met de code

Die Figma-koppeling is onderschat. Design en development spreken dezelfde tokens. Dat scheelt discussies en iteraties.

Installatie: stap voor stap

Je hebt een npm-gebaseerde build nodig. Hyvä UI werkt via een privé npm-registry na aankoop van je licentie. Na betaling ontvang je een registry-token.

Maak een .npmrc aan in de root van je project:

@hyva-ui:registry=https://registry.hyva.io/
//registry.hyva.io/:_authToken=JOUW_TOKEN_HIER

Vervang JOUW_TOKEN_HIER door het token uit je licentiebevestiging.

npm install @hyva-ui/components

Daarna heb je toegang tot alle componenten als HTML-snippets en eventuele Alpine.js-logica.

Hyvä UI levert eigen design tokens als Tailwind-presets. Voeg de preset toe aan je tailwind.config.js:

// tailwind.config.js
import hyvaUiPreset from '@hyva-ui/components/tailwind-preset';

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,php}',
    './node_modules/@hyva-ui/components/**/*.{html,js}',
  ],
  presets: [hyvaUiPreset],
  theme: {
    extend: {
      // Jouw eigen overrides hier
    },
  },
  plugins: [],
};

Let op de content-array. Zonder het pad naar node_modules/@hyva-ui/components purgt Tailwind de klassen van de componenten weg in productie. Dat is de meest voorkomende fout bij eerste installaties.

Hyvä UI-componenten met interactie gebruiken Alpine.js. Als je Alpine nog niet hebt:

npm install alpinejs

Initialiseer Alpine in je entry point:

// main.js
import Alpine from 'alpinejs';

window.Alpine = Alpine;
Alpine.start();

In een Hyvä theme is Alpine al aanwezig. Sla deze stap dan over.

Eerste component renderen

Een accordion als concreet voorbeeld. Kopieer de HTML uit de Hyvä UI-documentatie:

<div x-data="{ open: false }">
  <button
    class="flex w-full items-center justify-between px-4 py-3 text-left font-medium"
    @click="open = !open"
    :aria-expanded="open"
  >
    <span>Wat zijn de verzendkosten?</span>
    <svg
      class="h-5 w-5 transition-transform duration-200"
      :class="{ 'rotate-180': open }"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 20 20"
      fill="currentColor"
    >
      <path fill-rule="evenodd"
        d="M5.23 7.21a.75.75 0 011.06.02L10 11.168l3.71-3.938a.75.75 0 111.08 1.04l-4.25 4.5a.75.75 0 01-1.08 0l-4.25-4.5a.75.75 0 01.02-1.06z"
        clip-rule="evenodd" />
    </svg>
  </button>
  <div x-show="open" x-transition class="px-4 pb-4 text-sm text-gray-600">
    Verzending binnen Nederland is gratis vanaf 50 euro.
  </div>
</div>

Geen build-stap specifiek voor dit component. Tailwind pikt de klassen op via de content-configuratie. Alpine regelt de interactie. Dit is het HTML-first principe in de praktijk.

Start je dev-server en de accordion werkt direct.

Tailwind-tokens aanpassen aan je huisstijl

De preset definieert kleurvariabelen als tokens. Je overschrijft ze in theme.extend:

// tailwind.config.js
export default {
  presets: [hyvaUiPreset],
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#1a56db',
          dark: '#1e429f',
          light: '#76a9fa',
        },
        secondary: {
          DEFAULT: '#0e9f6e',
        },
      },
    },
  },
};

Componenten die bg-primary of text-primary gebruiken, passen zich automatisch aan. Je hoeft geen componenten te forken.

Dit is het verschil met een ad-hoc componentset die je van internet plakt. De tokens zijn het contract tussen design en code. Zie ook onze uitgebreidere gids over Hyvä UI en Tailwind-configuratie.

Performance: wat kun je verwachten?

Hyvä UI volgt de performance-filosofie van het Hyvä ecosysteem: ~95% minder JavaScript dan Luma-gebaseerde Magento-frontends. Lighthouse-scores van 95+ zijn haalbaar, geen marketingbelofte maar een realistische uitkomst bij correcte implementatie.

Dat getal is niet willekeurig. Luma laadt standaard jQuery, KnockoutJS, RequireJS en tientallen modules. Alpine.js is 15 kB gzipped. Dat is het volledige JavaScript-budget voor de meeste Hyvä UI-pagina's.

Vergelijking in context:

Wij zien bij klanten dat de Hyvä UI-overhead minimaal is. De componenten voegen weinig toe aan de Alpine-bundle omdat Alpine al aanwezig is.

Licentie: wat je koopt en voor wie

Eenmalig ~250 euro per developer of project, afhankelijk van het licentietype. Geen abonnement. Updates ontvang je zolang de licentie actief is. Raadpleeg de actuele licentievoorwaarden op de Hyvä-website voor exacte details — prijzen kunnen wijzigen.

Meer over wat de library inhoud via onze overzichtspagina Hyvä UI of het componentenoverzicht.

Wanneer Hyvä UI niet de juiste keuze is

Hyvä UI is niet altijd het beste gereedschap. Wees eerlijk voor je begint:

• Je project al een volwassen componentbibliotheek heeft (eigen design system, Shadcn, etc.) die goed werkt. Een tweede layer toevoegen creëert conflicten.
• Je team geen Tailwind gebruikt en ook geen plan heeft om dat te adopteren. De library is fundamenteel afhankelijk van de Tailwind-workflow.
• Je een React- of Vue-gebaseerde frontend bouwt zonder SSR. Hyvä UI is HTML-first en Alpine.js-gebaseerd. Dat past niet bij een component-driven JS-framework als primaire renderlaag.
• Je budget voor een Magento-project zo krap is dat de licentievergoeding een probleem is. Dan is het goedkoper om de paar componenten die je nodig hebt zelf te schrijven.

• Je in een Hyvä theme-context werkt. Dit is de sweet spot; het ecosysteem is op elkaar afgestemd.
• Je een Laravel- of statische site bouwt en geen zin hebt in het van scratch opbouwen van een toegankelijke componentset.
• Design en development moeten samenwerken via een gedeeld systeem. De Figma-koppeling maakt dat tastbaar.

Veelgemaakte fouten bij installatie

Kort en praktisch:

• Content-pad vergeten — Tailwind purgt klassen weg. Voeg altijd het pad naar node_modules/@hyva-ui toe aan content.
• Alpine twee keer initialiseren — In een Hyvä theme is Alpine al actief. Twee keer Alpine.start() aanroepen geeft conflicten.
• Tokens niet extenden maar overschrijven — theme.colors volledig overschrijven verwijdert de Hyvä UI-tokens. Gebruik altijd theme.extend.colors.
• Registry-token in git committen — Zet .npmrc in .gitignore of gebruik environment variables voor het token.

Volgende stappen

Installatie is tien minuten werk. De rest is keuzes maken: welke componenten gebruik je, hoe pas je tokens aan, hoe integreer je met je CMS of backend.

Wil je sparren over de setup voor jouw specifieke project? Onze senior developers kijken graag mee. Via /contact kun je een gratis Tech Check inplannen. Geen verkoopgesprek, gewoon technisch overleg.