Samouczek Nunjucks — Lily Design System

Co zbudujesz

Mały formularz kontaktowy renderowany po stronie serwera — pole z etykietą, przycisk wysyłania, zero ładunku JavaScript — najpierw surowy, potem ostylowany, w około 10 minut.

Zanim zaczniesz

Potrzebujesz gita, Node 22 lub nowszego i pnpm 10 lub nowszego. Dowolny potok Nunjucks się nadaje — Eleventy, Express lub czysty Nunjucks.

Krok 1 — Pobierz kod

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

Każdy komponent to katalog w components/ z macro.njk, jego testem i dokumentacją — na przykład components/button/macro.njk. Wskaż swój loader Nunjucks na components/ (w Eleventy dodaj go do ścieżki include) i importuj, czego potrzebujesz.

Krok 2 — Twój pierwszy komponent

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

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

Renderuje <button class="button" type="submit">Save</button>. Makra przyjmują jeden obiekt params: text (z escapowaniem) lub html (surowy), type, label dla elementu aria-labeloraz dopisywacz haczyka klasy.

Krok 3 — Złóż mały formularz

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

Ponieważ wszystko renderuje się na serwerze, przeglądarka dostaje czysty semantyczny HTML z haczykami klas — zerobajtowy ładunek JavaScript.

Sprawdź swoją pracę: załaduj stronę, a formularz wygląda surowo — dokładnie tak, jak zamierzono: stylowanie jest jeszcze przed nami. Naciśnij Tab: fokus przechodzi przez każdą kontrolkę, etykieta jest odczytywana, a wysyłanie działa. Zachowanie jest gotowe; wygląd należy do ciebie i jest następnym krokiem.

Krok 4 — Ostyluj go

Ostyluj haczyki — .button, .text-input, .label, .field — w swoim arkuszu stylów lub podlinkuj gotowy motyw w układzie bazowym:

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

Krok 5 — Zobacz, jak to wszystko działa

Aplikacja przykładowa Nunjucks + Eleventy buduje cały katalog jako statyczną witrynę ze stronami demo dla każdego komponentu:

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

Następne kroki

Motywy — w tym wzorzec ciasteczek Eleventy dla bezmigotliwego przełączania motywu w SSR.
Pomocniki preferencji — język i rozmiar tekstu.
Katalog komponentów — właściwości, ARIA i klawiatura dla każdego komponentu.

Pytania po drodze? Strona pomocy jest pełna odpowiedzi — a jeśli jakiś krok mógłby być jaśniejszy, daj nam znać a chętnie ulepszymy samouczek.