Nunjucks チュートリアル — Lily Design System

作るもの

小さなサーバーレンダリングのお問い合わせフォーム — ラベル付き入力、送信ボタン、JavaScript のペイロードはゼロ — まずは装飾なしで、次にスタイルを付けて、約 10 分で作ります。

始める前に

git、Node 22 以降、pnpm 10 以降が必要です。Nunjucks のパイプラインならどれでも使えます — Eleventy、Express、素の Nunjucks のいずれでも構いません。

ステップ 1 — コードを入手する

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

各コンポーネントは次の場所のディレクトリです: components/ (その中に macro.njk、テスト、ドキュメントがあります)— たとえば components/button/macro.njk。Nunjucks のローダーを次に向けます: components/ (Eleventy では includes のパスに追加します)。そして必要なものをインポートします。

ステップ 2 — 最初のコンポーネント

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

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

描画する要素: <button class="button" type="submit">Save</button>。マクロは 1 つの params オブジェクトを受け取ります: text (エスケープされる)または html (そのまま出力)、 type, label は aria-label、そしてクラスフックの追加用です。

ステップ 3 — 小さなフォームを組み立てる

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

すべてがサーバーで描画されるため、ブラウザーが受け取るのはクラスフックを付けた意味のある HTML だけで、JavaScript のペイロードは 0 バイトです。

動作の確認: ページを読み込むと、フォームは飾りのない見た目になります — 意図どおりで、スタイルはこれからです。 Tabキーを押してみましょう。フォーカスがすべてのコントロールを移動し、ラベルが読み上げられ、送信も動きます。動作は完成しています。見た目はあなた次第で、次のステップです。

ステップ 4 — スタイルを付ける

フックにスタイルを付けます — .button, .text-input, .label, .field — スタイルシートで、または基本レイアウトで既成のテーマをリンクします:

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

ステップ 5 — 動いているところを見る

Nunjucks + Eleventy サンプルアプリは、コンポーネントごとのデモページを備えた静的サイトとして、完全なカタログをビルドします:

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

次のステップ

テーマ設定 — ちらつきのない SSR でのテーマ切り替えのための、Eleventy のクッキーのパターンを含みます。
設定ヘルパー — 言語とテキストサイズ。
コンポーネントカタログ — コンポーネントごとのプロパティ、ARIA、キーボード操作。

途中で疑問があれば、ヘルプページに答えがたくさんあります。もし手順がもっと分かりやすくできるなら、お知らせください。喜んでチュートリアルを改善します。