Nunjucks-handleiding — Lily Design System

Wat je gaat bouwen

Een klein server-gerenderd contactformulier — invoerveld met label, verzendknop, nul JavaScript-lading — eerst kaal, dan vormgegeven, in ongeveer 10 minuten.

Voordat je begint

Je hebt git, Node 22 of nieuwer en pnpm 10 of nieuwer nodig. Elke Nunjucks-pijplijn werkt — Eleventy, Express of gewone Nunjucks.

Stap 1 — Haal de code op

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-headless
pnpm install
pnpm test        # vitest rendering every macro

Elke component is een map in components/ met een macro.njk, zijn test en zijn documentatie — bijvoorbeeld components/button/macro.njk. Wijs je Nunjucks-loader naar components/ (in Eleventy voeg je het toe aan het includes-pad) en importeer wat je nodig hebt.

Stap 2 — Je eerste component

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "submit" }) }}

Rendert <button class="button" type="submit">Save</button>. Macro's nemen één params-object: text (geëscaped) of html (rauw), type, label voor een aria-labelen een klassehaak-toevoeger.

Stap 3 — Stel een klein formulier samen

{% from "components/form/macro.njk" import form %}
{% from "components/label/macro.njk" import label %}
{% from "components/text-input/macro.njk" import textInput %}
{% from "components/button/macro.njk" import button %}

<form class="form" method="post">
  <div class="field">
    {{ label({ for: "name", text: "Full name" }) }}
    {{ textInput({ id: "name", name: "name", required: true }) }}
  </div>
  {{ button({ text: "Save", type: "submit" }) }}
</form>

Omdat alles op de server wordt gerenderd, krijgt de browser pure semantische HTML met de klassehaken — een JavaScript-lading van nul bytes.

Controleer je werk: laad de pagina en het formulier ziet er kaal uit — precies zoals bedoeld: de vormgeving komt nog. Druk op Tab: de focus beweegt door elk bedieningselement, het label wordt voorgelezen en verzenden werkt. Het gedrag is klaar; het uiterlijk is aan jou en komt hierna.

Stap 4 — Geef het vorm

Geef de haken vorm — .button, .text-input, .label, .field — in je stylesheet, of koppel een kant-en-klaar thema in je basislayout:

<link rel="stylesheet" href="/themes/united-kingdom-government-digital-service.css" />

Stap 5 — Zie alles werken

Nunjucks + Eleventy voorbeeld-app bouwt de volledige catalogus als statische site met demopagina's per component:

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-eleventy-examples
pnpm install && pnpm run dev

Volgende stappen

Thema's — inclusief het cookiepatroon van Eleventy voor flikkervrij SSR-thema wisselen.
Voorkeurenhelpers — taal en tekstgrootte.
Componentencatalogus — props, ARIA en toetsenbord per component.

Vragen onderweg? De helppagina staat vol antwoorden — en als een stap duidelijker kan, laat het ons weten en we verbeteren de handleiding graag.