---
name: daigakus-template
description: daigakus.com のホームページテンプレート（Astro）を作る・直すときに使う。content.json の契約、必須ページ、問い合わせフォーム、モジュールの表示、外部読み込みの禁止、提出物の規則と検査コマンドをまとめている。テンプレートの新規作成、デザイン変更、ページ追加、提出前チェックを AI に依頼するときに読む。
---

# daigakus.com テンプレート制作スキル

このリポジトリ（スターターパック）は、daigakus.com のテンプレートを 1 つ作るための Astro プロジェクトです。
お客様（テナント）が管理画面で入力した内容が `content.json` として届き、`astro build` で静的 HTML を作ります。

## 最初に読むもの

1. `GUIDE.md` — 仕様の正本。迷ったらここに従う
2. `docs/REFERENCE.md` — 標準セクション（`site`）と標準モジュールの項目一覧（`pnpm exec daigakus-template schema` でも同じ内容）
3. `template.json` と `src/lib/content.ts` — このテンプレートが受け取る値と、その読み込み方
4. `sample/content.json` と `sample/minimal.json` — 確認に使う入力の例

## この案件の形

- テンプレートは「`content.json` を読んで HTML を作る Astro プロジェクト」。**サーバーで動くコードは持たない**（`output: 'static'`）
- ビルドはネットワークなしで行われる。ビルド中に外部 API・CDN・フォントを取りに行けない
- 入力フォームはプラットフォームが用意する。テンプレートの仕事は「入力された値をどう見せるか」
- お客様が編集する内容は、必ず `site`（標準セクション）・`modules`（モジュール）・`template.json` の `schema`（テンプレート独自項目）として宣言する。宣言していない固定文言・画像はテンプレートに直接書いてよい（お客様は編集できない）
- 標準セクションの項目を `schema` に複製しない

## 絶対に守る決まり

1. **`contract` は `2`**。省略すると旧形式になり `site` と `modules` が届かない
2. **必須ページを出す**: `/`・`/news/`・`/about/` は常に。`/faq/` は `site.faq.items` が 1 件以上のとき、`/contact/` は `site.contact.enabled` のとき、`/legal/privacy/`・`/legal/terms/`・`/legal/tokushoho/` はそれぞれ `enabled` のとき。条件を満たさないページは出さず、ナビからも消す
3. **追加されたモジュールをすべて出す**。`template.json` の `modules` に書いたものは専用デザイン、それ以外は `moduleDisplaySections()` の汎用表示（`src/components/modules/Generic.astro`）。標準ページと衝突する id（`RESERVED_MODULE_SLUGS`）はページを作らない。`BANNER_MODULES`（`notice`）はページを作らず、レイアウトで全ページの上部に `noticeBanner` を出す
4. **問い合わせフォームの契約を変えない**: `method="post"`、`action` は `tenant.formEndpoint`、name は `name`・`email`・`phone`・`subject`・`body` と、ボット対策の見えない `website`
5. **外部の JS・CSS・フォント・iframe を読み込まない**。必要なものは同梱する。地図埋め込み・解析タグも不可
6. **Markdown は必ずサニタイズ**してから `set:html`。`src/lib/markdown.ts` を使う。Markdown 以外の入力値は `{value}` で出す
7. **入力 URL は `safeHttpUrl()` を通す**。`javascript:` などを `href` に入れない
8. **`vendor/daigakus-shared.tgz` を改変しない**（サーバーが配布物と sha256 で照合する）
9. **依存は npm レジストリのバージョン指定だけ**（SDK の `file:./vendor/daigakus-shared.tgz` を除く）。`overrides`・`resolutions`・`pnpm.*`・`.npmrc`・`pnpm-workspace.yaml`・`patches/` は使えない
10. **`template.json` の `id` を `starter` のまま提出しない**。`id` は最初に提出した人が永久に所有する。変更したら `sample/*.json` の `template.id` も揃える。`version` は `x.y.z` で、直したら必ず上げる（同じ版は上書きできない）

## 進め方

1. `GUIDE.md` と `src/` を読み、`template.json` の `id`・`name`・`description`・`version` を案件のものに変える
2. `pnpm install --ignore-scripts` → `pnpm dev` で `http://localhost:4321` を確認する
   - `--sample minimal` で、入力がほとんど無いサイトも確認する
3. `src/` のレイアウト・CSS・コンポーネントを作り替える。値は `src/lib/content.ts` から import する（`content.json` を直接読まない）
4. `template.json` の `schema` に、見た目の設定や独自コンテンツの入力欄を足す。**すべての項目に妥当な既定値**を用意するか、未入力でも崩れない表示にする
5. 提出前に必ず検査する（下のコマンド）。エラーが 0 になるまで直す
6. 変更内容と、実行した検査の結果を短く報告する（どのファイルを変えたか、`pnpm check` / `pnpm build` / `pnpm pack:zip` の結果）

## コマンド

| コマンド | すること |
| --- | --- |
| `pnpm dev [--sample 名前]` | プレビュー（`--sample minimal` で `sample/minimal.json`） |
| `pnpm check` | 提出前の静的検査＋すべての sample の検証＋`astro check` |
| `pnpm build` | すべての sample で審査と同じテストビルド。必須ページ・フォーム・外部読み込みを検査 |
| `pnpm pack:zip` | 検査とテストビルドのあと `submit/<id>-<version>.zip` を作る |
| `pnpm exec daigakus-template schema` | 標準セクション・標準モジュールの項目一覧 |

`pnpm dev` は保存で自動再読み込みされる。`--date YYYY-MM-DD` でビルド日を固定できる（ピン留めお知らせの確認用）。

## 見た目と品質の目安

- スマートフォン幅（360px 前後）で読める・押せる。ボタンやリンクは高さ 44px 程度
- 本文のコントラストは 4.5:1 以上
- 画像は `media[id].alt` を `alt` に入れる。装飾画像は `alt=""`
- 空の項目は見出しごと出さない（`sample/minimal.json` で確認）
- 文字を画像に焼き込まない（お客様が差し替えられなくなる）
- 行動ボタン（`resolveCtaButtons(site)`）はトップの目立つ位置に出す
- `thumbnail.png` は 1200x630・2MB まで。テンプレートの見た目に差し替える

## 提出前チェックリスト

- [ ] `pnpm check` がエラーなし
- [ ] `pnpm build` がすべての sample で通る
- [ ] `pnpm dev --sample minimal` で空のサイトが崩れない
- [ ] 必須ページが条件どおりに出る。ナビのリンク先が存在する
- [ ] フォームの `action`・`method`・name が契約どおり
- [ ] 外部の読み込みが 0（JS・CSS・フォント・iframe）
- [ ] `template.json` の `id` が `starter` ではない。`version` を上げた
- [ ] `vendor/daigakus-shared.tgz` を触っていない
- [ ] `pnpm pack:zip` が通り、`submit/` に zip ができた

## よくある失敗

| 症状 | 対処 |
| --- | --- |
| `content.json does not satisfy template.json` | sample の `data` が `schema` と合っていない。`pnpm check` の指摘箇所を直す |
| `/faq/ が出力されていません` など | そのページを出す条件（`site.faq.items` など）を満たす sample で出力していない |
| `外部のファイルを読み込んでいます` | フォント・JS を同梱し、相対パスで読み込む |
| `pnpm-workspace.yaml は同梱できません` | 削除する。`pnpm install --ignore-scripts` を使う（`pnpm pack:zip` も自動で除外する） |
| SDK が配布物と一致しない | スターターパックの `vendor/` をそのまま使う。古い場合は新しいスターターパックの `vendor/` に差し替えて `pnpm install --ignore-scripts` |

## してはいけないこと

- プラットフォームの仕様（`site` の項目名・フォームの送信先・モジュールのデータ形）を変える
- 審査を通すために検査を回避する（除外設定・独自スクリプト・外部からの取得）
- 依頼されていない大量のサンプル画像や、権利の不明な素材を追加する
- 既存のお客様の入力が壊れる `schema` の変更（キーの削除・必須化）を、版を上げずに行う

仕様と食い違う点や、判断できない点は、実装を進める前に質問する。
