Nunjucks-Tutorial — Lily Design System

Was du baust

Ein kleines serverseitig gerendertes Kontaktformular — beschriftetes Eingabefeld, Absenden-Schaltfläche, null JavaScript-Last — zuerst nackt, dann gestaltet, in etwa 10 Minuten.

Bevor du anfängst

Du brauchst git, Node 22 oder neuer und pnpm 10 oder neuer. Jede Nunjucks-Pipeline funktioniert — Eleventy, Express oder reines Nunjucks.

Schritt 1 — Den Code holen

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

Jede Komponente ist ein Verzeichnis in components/ mit einer macro.njk, ihrem Test und ihrer Dokumentation — zum Beispiel components/button/macro.njk. Richte deinen Nunjucks-Loader auf components/ (in Eleventy füge es dem Include-Pfad hinzu) und importiere, was du brauchst.

Schritt 2 — Deine erste Komponente

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

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

Rendert <button class="button" type="submit">Save</button>. Makros nehmen ein einziges Params-Objekt: text (escaped) oder html (roh), type, label für ein aria-labelund einen Anhänger für Klassen-Hooks.

Schritt 3 — Ein kleines Formular zusammensetzen

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

Weil alles auf dem Server gerendert wird, erhält der Browser reines semantisches HTML mit den Klassen-Hooks — null Byte JavaScript-Last.

Prüfe deine Arbeit: lade die Seite, und das Formular sieht schlicht aus — genau wie beabsichtigt: Die Gestaltung kommt noch. Drücke Tab: Der Fokus wandert durch jedes Bedienelement, das Label wird angesagt und das Absenden funktioniert. Das Verhalten ist fertig; das Aussehen gehört dir und kommt als Nächstes.

Schritt 4 — Gestalten

Gestalte die Hooks — .button, .text-input, .label, .field — in deinem Stylesheet, oder binde ein fertiges Theme in deinem Basislayout ein:

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

Schritt 5 — Alles in Aktion sehen

Nunjucks + Eleventy Beispiel-App baut den vollständigen Katalog als statische Website mit Demoseiten pro Komponente:

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

Nächste Schritte

Theming — einschließlich des Eleventy-Cookie-Musters für flackerfreies SSR-Theme-Umschalten.
Einstellungs-Helper — Sprache und Textgröße.
Komponentenkatalog — Props, ARIA und Tastatur pro Komponente.

Fragen unterwegs? Die Hilfeseite steckt voller Antworten — und wenn ein Schritt klarer sein könnte, sag es uns und wir verbessern das Tutorial gern.