Tutorial Nunjucks — Lily Design System

Cosa costruirai

Un piccolo modulo di contatto renderizzato lato server — campo con etichetta, pulsante di invio, zero JavaScript inviato — prima spoglio, poi stilizzato, in circa 10 minuti.

Prima di iniziare

Servono git, Node 22 o successivo e pnpm 10 o successivo. Va bene qualsiasi pipeline Nunjucks — Eleventy, Express o Nunjucks semplice.

Passo 1 — Ottieni il codice

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

Ogni componente è una directory in components/ con un macro.njk, il suo test e la sua documentazione — ad esempio components/button/macro.njk. Punta il tuo loader Nunjucks a components/ (in Eleventy, aggiungilo al percorso degli include) e importa ciò che ti serve.

Passo 2 — Il tuo primo componente

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

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

Rende <button class="button" type="submit">Save</button>. Le macro prendono un unico oggetto params: text (con escape) oppure html (grezzo), type, label per un aria-labele un accodatore di hook di classe.

Passo 3 — Componi un piccolo modulo

{% 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>

Poiché tutto viene renderizzato sul server, il browser riceve HTML semantico puro con gli hook di classe — zero byte di JavaScript.

Controlla il lavoro: carica la pagina e il modulo appare spoglio — esattamente come previsto: lo stile deve ancora venire. Premi Tab: il focus si sposta su ogni controllo, l'etichetta viene annunciata e l'invio funziona. Il comportamento è fatto; l'aspetto è tuo, ed è il prossimo passo.

Passo 4 — Dagli uno stile

Stilizza gli hook — .button, .text-input, .label, .field — nel tuo foglio di stile, oppure collega un tema pronto nel layout di base:

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

Passo 5 — Guarda tutto in funzione

App di esempio Nunjucks + Eleventy costruisce l'intero catalogo come sito statico con pagine dimostrative per componente:

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

Prossimi passi

Temi — incluso il pattern con cookie di Eleventy per cambiare tema in SSR senza sfarfallio.
Helper delle preferenze — lingua e dimensione del testo.
Catalogo dei componenti — proprietà, ARIA e tastiera per ogni componente.

Domande lungo la strada? La pagina di aiuto è piena di risposte — e se un passo può essere più chiaro, faccelo sapere e miglioreremo volentieri il tutorial.