AK²Engine › ドキュメント › レシピ
ドキュメント

レシピ

レシピの考え方・使い方・作り方

← 目次に戻る

レシピとは

レシピは 見本（サンプル） です。そのまま使っても、コピーして改変しても構いません。

レシピの実体は .njk（テンプレート）+ .css（スタイル） のセットで、プロジェクトの _sections/ ディレクトリに配置します。

src/_sections/
  hero-basic.njk       テンプレート（HTML構造）
  hero-basic.css       スタイル
  card-grid-basic.njk
  card-grid-basic.css

使い方の3パターン

1. そのまま使う

sections:
  - template: hero-basic
    title: "ようこそ"
    lead: "サイトの説明文"

2. CSS変数で微調整する

レシピの CSS 冒頭に 調整ポイント がまとまっています。extraClass で CSS 変数を上書きするだけで、テンプレートを編集せずに見た目を変えられます。

sections:
  - template: hero-basic
    title: "ようこそ"
    extraClass: "my-hero-variant"

/* site.css */
.my-hero-variant {
  --hero-basic-bg: #1a1a2e;
  --hero-basic-subtitle-color: #f59e0b;
  --hero-basic-title-size: clamp(1.8rem, 4vw, 3rem);
}

同じページ内で同じレシピを複数回使いつつ、それぞれ異なる見た目にする場合に便利です。

3. フォークして大きく改変する

CSS 変数では足りないほどの変更が必要なときは、レシピをコピーして自由に書き換えます。

npx ak2 create my-hero --from hero-basic

これで hero-basic のコピーが my-hero.njk + my-hero.css として生成され、CSS クラス名も自動でリネームされます。あとは好きなように改変してください。

CSS 調整変数パターン

すべてのスターターキットレシピは、CSS の冒頭に調整変数をまとめています。

/* hero-basic.css */
.hero-basic {
  --hero-basic-padding: 8rem 0 6rem;
  --hero-basic-bg: var(--color-bg-dark, #0f172a);
  --hero-basic-title-size: clamp(2rem, 5vw, 3.5rem);
  --hero-basic-subtitle-color: var(--color-secondary, #00C6FF);
  padding: var(--hero-basic-padding);
  background: var(--hero-basic-bg);
}

.njk の冒頭コメントには YAML パラメータ と CSS 調整変数 の一覧が記載されています。「どこを触ればどう変わるか」のクイックリファレンスです。

レシピの作り方

テンプレート（.njk）

フロントマターの値は section.* でアクセスします。

{# my-card — カードセクション
   ─────────────────────────────────────
   YAML パラメータ:
     title      - 見出し
     items[]    - カードデータ配列
     extraClass - 追加CSSクラス
     style      - CSS変数の上書き
   CSS 調整変数:
     --my-card-padding : セクション余白
     --my-card-bg      : 背景色
   ───────────────────────────────────── #}
<section class="my-card{% if section.extraClass %} {{ section.extraClass }}{% endif %}" style="{{ section.style }}">
  <div class="container">
    <h2 class="my-card__title">{{ section.title }}</h2>
    <div class="my-card__grid">
      {% for item in section.items %}
      <div class="my-card__item">
        <h3>{{ item.name }}</h3>
        <p>{{ item.desc }}</p>
      </div>
      {% endfor %}
    </div>
  </div>
</section>

スタイル（.css）

/* ── 調整ポイント ── */
.my-card {
  --my-card-padding: 4rem 0;
  --my-card-bg: white;
  padding: var(--my-card-padding);
  background: var(--my-card-bg);
}
.my-card__title {
  font-size: 1.8rem;
  margin-bottom: 2rem;
}
.my-card__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 1.5rem;
}
.my-card__item {
  padding: 1.5rem;
  border: 1px solid var(--color-border, #e0e0e0);
  border-radius: var(--radius-sm, 4px);
}

フロントマターで使う

---
sections:
  - template: my-card
    title: "サービス紹介"
    items:
      - name: "プラン A"
        desc: "基本プラン"
      - name: "プラン B"
        desc: "プレミアムプラン"
---

ルール

CSS クラス命名

テンプレート名をプレフィックスに使います。BEM 風で統一してください。

テンプレート名: my-card
  → .my-card            ルート
  → .my-card__title     子要素
  → .my-card__item      子要素

これによりレシピ同士のクラス名衝突を防ぎます。

自己完結

レシピはエンジン内部のマクロやブロックに依存しないでください。.njk + .css だけで完結するように書きます。

extraClass と style の対応

extraClass と style はすべてのレシピで対応してください。CSS 変数でのカスタマイズを可能にする基盤です。

<section class="my-card{% if section.extraClass %} {{ section.extraClass }}{% endif %}" style="{{ section.style }}">

調整変数の命名

CSS 調整変数は --レシピ名-用途 の形式にします。

--hero-basic-padding       ✓（レシピ名 + 用途）
--padding                  ✗（名前空間がない）

レシピの保存

作成したレシピをレシピ集に登録するには:

npx ak2 save my-card "カードグリッド。サービス紹介用。"

これで ak2-recipes に追加され、registry.json も自動で更新されます。以降 npx ak2 add my-card で他のプロジェクトにも追加できます。

エフェクト付きセクション

レシピ内でエフェクト用の canvas を配置できます。

<section class="my-hero" style="position:relative; overflow:hidden;">
  {% for effect in section.effects | default([]) %}
  {% set effectName = effect.name if effect.name else effect %}
  <canvas data-section-effect="{{ effectName }}"
    {% if effect.name %}data-section-effect-options="{{ effect | dump | escape }}"{% endif %}
    style="position:absolute;inset:0;width:100%;height:100%;pointer-events:none;z-index:0;mix-blend-mode:screen;">
  </canvas>
  {% endfor %}
  <div class="container" style="position:relative; z-index:1;">
    <h1 class="my-hero__title">{{ section.title }}</h1>
  </div>
</section>

フロントマター側:

sections:
  - template: my-hero
    title: "タイトル"
    effects:
      - name: BgEffectSnow
        count: 50

スターターキット

エンジンには以下のレシピが付属しています。CLI で追加できます。

レシピ名 用途 CSS 調整変数 デモ
hero-basic ヒーローセクション（ファーストビュー） padding, bg, color, min-height, title-size, subtitle-color, lead-opacity —
cta-basic コールトゥアクション（誘導） padding, title-size, btn-bg, btn-color, btn-radius —
faq-basic FAQ アコーディオン padding, bg, title-size, label-color, item-bg, item-radius —
card-grid-basic カードグリッド（機能紹介・カタログ） padding, bg, title-size, label-color, card-bg, card-radius, card-min, gap —
stats-basic 数字ハイライト（実績・統計） padding, bg, title-size, label-color, num-size, num-color, gap デモ
timeline-basic タイムライン（利用の流れ・沿革） padding, bg, title-size, label-color, line-color, dot-color デモ
pricing-basic 料金プラン表（SaaS・サービス） padding, bg, title-size, label-color, card-bg, card-radius, accent, gap デモ
testimonial-basic お客様の声（レビュー・推薦） padding, bg, title-size, label-color, card-bg, card-radius, gap デモ
logo-cloud-basic ロゴクラウド（取引先・掲載実績） padding, bg, title-size, label-color, logo-height, gap, opacity デモ
text-basic 汎用テキスト（挨拶文・会社概要） padding, bg, title-size, max-width デモ
team-basic チーム・スタッフ紹介 padding, bg, title-size, label-color, card-bg, card-radius, img-size, gap デモ
gallery-basic 写真ギャラリー（実績・作品集） padding, bg, title-size, label-color, radius, gap, col-min デモ
feature-list-basic 機能一覧（アイコン+説明） padding, bg, title-size, label-color, icon-size, icon-color, gap デモ
media-basic 画像+テキスト横並び padding, bg, title-size, label-color, img-radius, gap デモ
table-basic 比較表・スペック表 padding, bg, title-size, label-color, head-bg, border, stripe-bg デモ
banner-basic お知らせ・告知バナー padding, bg, color, link-color デモ
contact-basic お問い合わせフォーム padding, bg, title-size, label-color, input-bg, input-radius, btn-bg, btn-color デモ

詳しくは CLI ツール を参照してください。

前のページ: ← v2 アーキテクチャ概要 | ↑ 目次