Tutoriel Nunjucks — Lily Design System

Ce que vous allez construire

Un petit formulaire de contact rendu côté serveur — champ avec étiquette, bouton d'envoi, zéro charge JavaScript — d'abord nu, puis stylé, en 10 minutes environ.

Avant de commencer

Il vous faut git, Node 22 ou plus récent et pnpm 10 ou plus récent. Tout pipeline Nunjucks convient — Eleventy, Express ou Nunjucks simple.

Étape 1 — Récupérer le code

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

Chaque composant est un répertoire dans components/ avec un macro.njk, son test et sa documentation — par exemple components/button/macro.njk. Pointez votre chargeur Nunjucks vers components/ (dans Eleventy, ajoutez-le au chemin includes) et importez ce dont vous avez besoin.

Étape 2 — Votre premier composant

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

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

Rend <button class="button" type="submit">Save</button>. Les macros prennent un seul objet params : text (échappé) ou html (brut), type, label pour un aria-labelet un ajouteur de crochet de classe.

Étape 3 — Composer un petit formulaire

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

Comme tout est rendu sur le serveur, le navigateur reçoit du HTML sémantique pur avec les crochets de classe — une charge JavaScript de zéro octet.

Vérifiez votre travail : chargez la page et le formulaire paraît nu — exactement comme prévu : le style reste à venir. Appuyez sur Tab: le focus traverse chaque contrôle, l'étiquette est annoncée et l'envoi fonctionne. Le comportement est fait ; l'apparence est la vôtre et c'est l'étape suivante.

Étape 4 — Le styler

Stylez les crochets — .button, .text-input, .label, .field — dans votre feuille de style, ou liez un thème prêt à l'emploi dans votre mise en page de base :

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

Étape 5 — Voir le tout fonctionner

L'application d'exemple Nunjucks + Eleventy construit le catalogue complet comme un site statique avec des pages de démonstration par composant :

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

Étapes suivantes

Thèmes — y compris le motif de cookies d'Eleventy pour un changement de thème SSR sans scintillement.
Assistants de préférences — langue et taille du texte.
Catalogue de composants — propriétés, ARIA et clavier par composant.

Des questions en chemin ? La page d'aide regorge de réponses — et si une étape peut être plus claire, dites-le-nous et nous améliorerons volontiers le tutoriel.