Tutorial de Nunjucks — Lily Design System

Qué vas a construir

Un pequeño formulario de contacto renderizado en el servidor: campo con etiqueta, botón de envío, cero carga de JavaScript; primero desnudo, luego con estilo, en unos 10 minutos.

Antes de empezar

Necesitas git, Node 22 o posterior y pnpm 10 o posterior. Sirve cualquier canalización de Nunjucks: Eleventy, Express o Nunjucks simple.

Paso 1: Obtén el 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 es un directorio en components/ con un macro.njk, su prueba y su documentación; por ejemplo components/button/macro.njk. Apunta tu cargador de Nunjucks a components/ (en Eleventy, añádelo a la ruta de includes) e importa lo que necesites.

Paso 2: Tu primer componente

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

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

Renderiza <button class="button" type="submit">Save</button>. Las macros toman un único objeto params: text (escapado) o html (sin procesar), type, label para un aria-labely un añadidor de gancho de clase.

Paso 3: Compón un formulario pequeño

{% 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 todo se renderiza en el servidor, el navegador recibe HTML semántico puro con los ganchos de clase: una carga de JavaScript de cero bytes.

Comprueba tu trabajo: carga la página y el formulario se ve sencillo, tal como se pretendía: el estilo aún está por venir. Pulsa Tab: el foco recorre cada control, se anuncia la etiqueta y el envío funciona. El comportamiento está hecho; el aspecto es tuyo y es el siguiente paso.

Paso 4: Dale estilo

Da estilo a los ganchos: .button, .text-input, .label, .field , en tu hoja de estilos, o enlaza un tema ya hecho en tu diseño base:

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

Paso 5: Míralo todo funcionando

La aplicación de ejemplo Nunjucks + Eleventy construye el catálogo completo como un sitio estático con páginas de demostración 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

Próximos pasos

Temas , incluido el patrón de cookies de Eleventy para el cambio de tema SSR sin parpadeo.
Asistentes de preferencias : idioma y tamaño del texto.
Catálogo de componentes : propiedades, ARIA y teclado por componente.

¿Dudas por el camino? La página de ayuda está llena de respuestas, y si algún paso puede ser más claro, cuéntanoslo y con gusto mejoraremos el tutorial.