Tutorial de Nunjucks — Lily Design System

O que vai construir

Um pequeno formulário de contacto renderizado no servidor — campo com etiqueta, botão de envio, zero carga de JavaScript — primeiro simples, depois estilizado, em cerca de 10 minutos.

Antes de começar

Precisa de git, Node 22 ou posterior e pnpm 10 ou posterior. Qualquer pipeline Nunjucks serve — Eleventy, Express ou Nunjucks simples.

Passo 1 — Obter o código

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

Cada componente é um diretório em components/ com um macro.njk, o seu teste e a sua documentação — por exemplo components/button/macro.njk. Aponte o seu carregador de Nunjucks para components/ (no Eleventy, adicione-o ao caminho de includes) e importe o que precisar.

Passo 2 — O seu primeiro componente

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

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

Renderiza <button class="button" type="submit">Save</button>. As macros recebem um único objeto params: text (com escape) ou html (em bruto), type, label para um aria-labele um acrescentador de gancho de classe.

Passo 3 — Componha um pequeno formulário

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

Como tudo é renderizado no servidor, o navegador recebe HTML semântico puro com os ganchos de classe — uma carga de JavaScript de zero bytes.

Verifique o seu trabalho: carregue a página e o formulário parece simples — exatamente como pretendido: o estilo ainda está por vir. Prima Tab: o foco percorre cada controlo, a etiqueta é anunciada e o envio funciona. O comportamento está feito; o aspeto é seu e é o passo seguinte.

Passo 4 — Estilize-o

Estilize os ganchos — .button, .text-input, .label, .field — na sua folha de estilos, ou ligue um tema pronto no seu layout base:

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

Passo 5 — Veja tudo a funcionar

A aplicação de exemplo Nunjucks + Eleventy constrói o catálogo completo como um site estático com páginas de demonstração por 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

Passos seguintes

Temas — incluindo o padrão de cookies do Eleventy para alternância de tema SSR sem cintilação.
Auxiliares de preferências — idioma e tamanho do texto.
Catálogo de componentes — propriedades, ARIA e teclado por componente.

Dúvidas pelo caminho? A página de ajuda está cheia de respostas — e se algum passo puder ser mais claro, diga-nos e melhoraremos o tutorial com todo o gosto.