page-template

HTML ショーケース — ページテンプレート

自己進化型スキル：このスキルは使用するほど改善されます。手順が間違っている場合、パラメーターが変化した場合、または回避策が必要になった場合は、後回しにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

ナビゲーション構造がファイルシステムのレイアウトそのものとなる静的な HTML ミニサイトです。すべてのページは jsDelivr で配信される共通の CSS カーネルにリンクします。自動検出されるナビゲーションレールとマスターの site-map.html は、サイトルート配下に作成した任意のディレクトリから scripts/build-nav.py によって生成されます。ページは純粋な HTML で、ページごとの CSS オーバーライドを任意で追加できます。このアーキテクチャは 5 つの原則に基づいています。拡張やフォークの前に、WHY を理解するため references/principles.md を先に読み、ナビゲーションの仕様については references/sitemap.md を読んでください。

サイトマップを標準として使う

このスキルで作成するすべてのサイトは、同じ構成になります。

<site-root>/
  index.html              ← site home (recommended)
  overrides.css           ← optional per-site tweaks
  auto-nav.css            ← generated by build-nav.py
  auto-nav.js             ← generated by build-nav.py
  site-map.html           ← generated by build-nav.py
  <section-1>/            ← any subdirectory becomes a "section"
    index.html
    page-a.html
    page-b.html
  <2026-05-02-audit>/     ← YYYY-MM-DD- prefix sorts sections newest-first
    index.html
    findings.html

ナビゲーションを手書きする必要はありません。希望するディレクトリ構成に HTML ファイルを追加してから、scripts/build-nav.py --root <site-root> を実行します。このスクリプトはツリーをたどり、site-map.html を生成し、ナビゲーションレールの CSS／JS を書き込み、コメントマーカーを使って同じナビゲーションレールをすべてのページに挿入します。再実行しても結果は変わりません。

アーキテクチャとトレードオフについては、references/sitemap.md を参照してください。

手順ではなく、原則のレベルでこのスキルを読む

このスキルの具体的な成果物（クラス名、ファイルパス、特定の CDN URL、コミットメッセージの規約、さらには「section」という命名など）はすべて、少数の基本原則を具体化したものです。原則を理解すれば、アーキテクチャを壊さずに、個々の具体例から適切に逸脱できます。手順に従うだけでは、自分のケースに合わない状況に初めて遭遇したとき、システムを歪めてしまいます。

原則は references/principles.md にまとめられています。

1. 信頼できる唯一の情報源 — 見た目に関する判断はすべて 1 つのファイルに集約されます
2. アトミックよりセマンティック — クラス名は要素が 何であるか を表します
3. トークン駆動 — 具体的な値はすべて CSS カスタムプロパティから取得します
4. カスケードの規律 — @layer の順序によって特異性を全体的に制御します
5. 隠れた状態を作らない — JS もインライン CSS も、分散したオーバーライドも使いません
6. ファイルシステムをサイトマップにする — ディレクトリ構成がナビゲーショングラフになります

さらに、AI との協働パターン（この設計が LLM に適している理由）と、コピーではなく CDN を使う根拠も含まれています。

3 層の階層構造

層	変更可能性	制御する内容	配置場所
H1 — カーネル	一度編集すると全体に反映されます	トークン（色、余白、文字）、リセット、基本要素、コンポーネント	assets/showcase.css（jsDelivr CDN）
H2 — コンポジション	ページごと	セクションの順序、コンテンツ、セマンティックマークアップ	HTML ファイル自体
H3 — オーバーライド	ページごと（任意）	1 つのページの色や密度の調整	HTML と同じ場所にある overrides.css

カーネルは、あらゆる視覚的な判断における SSoT です。HTML でスタイルを新たに定義することはなく、カーネルで定義されたコンポーネントを配置するだけです。1 つのページをカスタマイズするには、overrides.css に CSS 変数をいくつか追加します。すべてのページをカスタマイズするには、カーネルを編集します。

自動ナビゲーションレールは手書きではなく、_生成_されます。スタイルは auto-nav.css（build-nav.py によって書き込まれます）に定義されています。各ページの <body> 内にある と のマーカーの間にコンテンツが挿入されます。

レールとマスターの site-map.html は、ホストページのテーマにかかわらず、常にダークです（slate-950 のサーフェス、slate-300 のテキスト、indigo-400 のアクセント）。レールはすべてのページに共通する要素です。テーマを固定することで、重ねて表示されるページが明るい業者向けショーケースでも、ダークなテレメトリーダッシュボードでも、視覚的な一貫性を保ちます。

セクション内のページはアルファベット順ではなく、作成順で表示されます。

• index.html は常に最初です。
• index_iter_<N>_<slug>.html の命名規則に従うページは、N の数値順に並びます（そのため、iter_10 は iter_1 の後ではなく、iter_9 の後になります）。
• その他のトップレベルページは、ファイルシステムの作成時刻（macOS の st_birthtime。編集や再ビルドでは変更されません）で並びます。
• ネストされたページは、元のサブディレクトリの順序、インデックス優先、アルファベット順のグループ分けに従います。

レールの実行時の動作：

• 初回読み込み時：折り返しのない最長リンクに合わせて幅を自動調整します（width: max-content を使って、レールの現在のサイズにかかわらず、各リンクの本来の幅を測定します）。幅は [220, 760]px に制限されます。
• 右端のハンドルをドラッグ：幅を [220, 1200]px の範囲で手動調整できます。選択した幅は localStorage に保存されます。
• ハンドルをダブルクリック：保存した幅を消去して自動調整を再実行します（意味としては「スマートなデフォルトにリセット」です）。
• ハンドルには 14px の操作領域があり、常に表示される 2px のインジケーターラインと、2 種類の操作方法を説明するホバーツールチップが備わっています。
• セクション内の前へ／次へ：セクション内のページでは、「Site」ヘッダー行にコンパクトな ‹ › ボタン（高さは増えません）が表示されます。また、Chrome で安全に使用できる単独の [ ／ ] キーボードショートカットも使えます。‹ ／ [ は上の兄弟ページ（新しいページ）へ、› ／ ] は下の兄弟ページ（古いページ）へ移動します。リストの端では、該当するボタンはグレーアウトします。修飾キーを押している間、または検索ボックスにフォーカスがある間はキー入力が無視されるため、入力を妨げることはありません。

検索はデフォルトで有効です

各レール（およびマスターの site-map.html）の最上部には、Pagefind を使った 検索 セクションが設置されます。Pagefind は Rust で構築された静的検索ツールで、サーバーもビルドパイプラインも不要な、自己完結型のインデックスと約 70 KB のクライアント UI を生成します。

設定方法：

• build-nav.py は、各ページの <head> に 4 つのタグを厳密な順序で挿入します：Pagefind の CSS → 自動ナビゲーションの CSS → Pagefind の JS → 自動ナビゲーションの JS。
• レールの最初のセクションは <div id="auto-nav-search"></div> です。Pagefind の読み込み後に auto-nav.js が new PagefindUI({...}) を呼び出します。
• インデックス本体は <site-root>/pagefind/ にあり、pagefind --site <site-root> を実行して生成します。
• scripts/site.sh nav は build-nav.py と pagefind --site の両方を実行します。レールを再構築するたびに、検索インデックスも自動的に更新されます。

pagefind がインストールされていない場合も、検索入力欄は表示されますが機能しません。window.PagefindUI が未定義の場合、auto-nav.js の mountSearch() は処理を終了します。brew install pagefind でインストールするか、公式のインストール手順を参照してください。

プッシュ時のフックによる自動再同期

install.sh --hook は .githooks/pre-push に Git の pre-push フックをインストールし、git config core.hooksPath .githooks を設定します。その後、git push main を実行するたびに、以下が自動的に行われます。

1. リポジトリ内のすべてのサイトディレクトリ（site-map.html を含むディレクトリ）を自動検出します。
2. scripts/site.sh nav <site-dir> を実行します（レールと検索インデックスを再構築します）。
3. scripts/site.sh push <site-dir> を実行します（Tailscale 経由で myhost に rsync します）。

このフックは処理をブロックしません。rsync に失敗しても（携帯回線、コーヒーショップ、myhost の停止など）、GitHub へのプッシュは続行されます。スキップ用の環境変数：

変数	効果
NO_HTMLSHOWCASE_HOOK=1	フック全体をスキップします
NO_HTMLSHOWCASE_SYNC=1	ナビゲーションと検索は実行し、rsync はスキップします
NO_HTMLSHOWCASE_SEARCH=1	pagefind の再生成処理をスキップします
HTMLSHOWCASE_SITES="a b c"	自動検出の代わりに明示的なリストを指定します

4 つの貢献者の立場

タスクに合った役割を選んでください。各役割のワークフロー全体については、references/contributing.md を参照してください。

役割	タスクの例	編集対象	影響範囲
利用者	「請負業者のショーケースサイトを作ってください」	自分の HTML	自分のサイトのみ
カスタマイザー	「このサイトを自社ブランドのティールカラーで再テーマ化してください」	overrides.css	自分のサイトのみ
コントリビューター	「カーネルに .timeline コンポーネントを追加してください」	上流のカーネル CSS	このカーネルを使うすべてのサイト
パブリッシャー	「チームでカーネルをフォークし、自分たちの GitHub から公開します」	自分のフォークのカーネル	自分の CDN URL を指定するサイト

このスキルを使う場面

• 監査、コミット、メトリクス、レポート、請負業者のショーケース、テレメトリ表示、週次ダイジェストなど、構造化された作業記録を含む静的 HTML サイト（1 ページまたは複数ページ）を作成する場合
• インライン CSS のページを、共有デザインシステムと自動ナビゲーションに置き換える場合
• 請負業者のポートフォリオ、週次ダイジェストのアーカイブ、リリースノートのハブへと成長する複数ページのミニサイトを立ち上げる場合。ナビゲーションを手作業で保守する必要はありません。

次の用途には使用しないでください：ブログ記事、マーケティング用ランディングページ、インタラクティブなウェブアプリ。

このスキルに含まれるもの

パス	役割
templates/index.html	サイトホームの骨組み（ヒーロー＋3つの例のセクション＋フッター＋マーカー）
templates/section-index.html	セクションのランディングページの骨組み
templates/overrides.css.example	サイトごとのカスタマイズ用リファレンス（overrides.css に名前を変更）
templates/lychee.toml	リンクチェッカーの設定
scripts/build-nav.py	汎用サイトマップビルダー — 自動ナビゲーション＋site-map.html 生成
scripts/check-orphan-pages.py	標準ライブラリのみを使用する孤立ページグラフの検証ツール
scripts/site.sh	ナビゲーションをビルド＋検証＋Tailscale 経由で myhost にプッシュ（下記参照）
scripts/install.sh	ワンショットのブートストラップ：3つのスクリプトを任意のリポジトリにインストール
references/principles.md	WHY — 5つの原則＋AI パターン
references/sitemap.md	HOW — ファイルシステムをサイトマップとする規約、レールのレンダリング
references/contributing.md	HOW — 4つのスタンスと完全なワークフロー
references/publishing.md	WHERE — 配信先（CDN と tailnet）＋myhost のセットアップ

CSS カーネル本体はプラグインレベルにあり （plugins/html-showcase/assets/showcase.css）、jsDelivr から配信されます — 骨組みの HTML はローカルファイルではなく、公開 CDN の URL を参照します。

完成したサイトのホスティング先

2つの配信先、2つの役割です。

配信先	配置するもの	使用するタイミング
jsDelivr CDN（公開）	カーネル CSS のみ	常時 — すべてのページが1つの共有 URL からカーネルをインポートします
tailnet 上の myhost	レンダリング済みのサイト	内部向けの対象者がデフォルト（DNS 不要、認証 UI 不要、公開されません）
jsDelivr / Pages / Workers	レンダリング済みのサイト	外部の読者が実際にそのページを必要とする場合のみ

監査レポート、請負業者向けショーケース、テレメトリ表示、週次ダイジェストなど、 内部向けサイトには、myhost tailnet 経由が最も手間の少ない選択肢です。 任意のリポジトリでの導入は1つのコマンドで完了します。

ROOT="$(cc-plugin-root html-showcase)"
bash "$ROOT/skills/page-template/scripts/install.sh"

これにより、3つのパイプラインスクリプト（build-nav.py、 check-orphan-pages.py、site.sh）が <repo>/scripts/ にインストールされ、 .gitignore に **/.published.json が追加されます。インストーラーは 冪等で（再実行しても何も変更されず）、破壊的な操作は行いません （上書きするには --force を指定します）。スターターサイトディレクトリも作成する場合は、次を実行します。

bash "$PLUGIN/skills/page-template/scripts/install.sh" --site contractor-site

その後、scripts/site.sh push <site-dir> を実行するとサイトマップを再生成し、 ローカルで検証（lychee＋孤立ページチェック）してから、 myhost:~/sites/<repo>/<site-dir>/ に rsync します。配信先は https://myhost.tailnet-name.ts.net:8448/<repo>/<site-dir>/ です。プッシュ時の ゲート（build-nav＋lychee＋孤立ページチェック）が唯一のゲートです。仕組みの全容、 URL の形式、myhost を使用しない場合、および myhost の初回セットアップについては、 references/publishing.md を参照してください。

汎用の密度調整用ノブ

showcase.css の冒頭にある2つの CSS カスタムプロパティで、ビジュアルのリズム全体を 調整できます。overrides.css でどちらかを上書きして、サイトごとに調整します。

:root {
  --density: 0.85; /* spacing multiplier; 1.0 baseline, lower = tighter */
  --font-scale: 0.94; /* type multiplier; 1.0 baseline, lower = smaller */
}

カーネル内のすべてのパディング、ギャップ、マージン、セクションのリズムは スペーシングスケールから導出されます。スペーシングスケールは --density から、 本文のフォントサイズは --font-scale から導出されます。コンポーネント CSS に 散在するマジックナンバーはありません — references/principles.md の原則3を参照してください。

コンポーネントの用語

カーネルでは、HTML で使用する以下のセマンティッククラスを定義しています。すべてのクラスを確認するには、カーネルの CSS を開き、クラスセレクターを検索してください。

クラス	目的
.hero + .hero__inner / __eyebrow / __title / __lede / __cta-row	グラデーション付きのトップバナー
.chip--solid / .chip--ghost	ヒーローの CTA ボタン
.metric-grid + .metric-card	数値をひと目で確認できるパネル。修飾子は --accent、--success、--warning
.phase-grid + .phase-card	フェーズ別のタイムラインカード。修飾子は --audit、--fix、--perf
.commit-stack + .commit-card	SHA チップと詳細グリッドを備えたコミットの詳細カード
.bug-grid + .bug-card (--high modifier)	コンパクトな課題カード
.feature-grid + .feature-card	アイコン付きの汎用的な 4 列のショーケースグリッド
.reco-list + .reco-item (--p0 / --p1 / --p2)	優先度順の推奨事項
.badge (--high / --medium / --low / --success / --info / --neutral / --accent)	重大度／ステータスのラベル
.section-head / .section-intro	セクションごとのタイトル行と概要段落
.shell	最大幅とレスポンシブなパディングを備えた中央揃えのコンテンツシェル
.site-footer + .site-footer__grid / __legal	出所情報を記載するフッター

自動ナビゲーションレールは、カーネルに属さない独自のクラス（.auto-nav-rail、 .rail-link、.rail-section など）を auto-nav.css で定義しているため、 ナビゲーションを自己完結させ、カーネルを導入せずにレールだけをリポジトリへ 導入できます。

この表にないコンテンツコンポーネントが必要な場合は、次の 2 つの方法があります。どちらも適切な方法であり、両方とも references/contributing.md に記載されています。

• カーネルに追加する（スタンス 3）：components @layer にセマンティックなクラス名を追加し、トークンを参照する値と BEM 修飾子のバリエーションを使用します。
• ローカルオーバーライドを使用する（スタンス 2）：パターンが本当に 1 つのページに固有の場合に限ります。繰り返し使うパターンはカーネルに追加します。

クイックスタート（コンシューマースタンス、サイトマップで整理）

最も手早い方法は、インストーラーを実行してパイプラインスクリプトとスターターサイトをセットアップし、その後、反復して改善することです。

ROOT="$(cc-plugin-root html-showcase)"

# 1. Bootstrap the pipeline + starter site directory
bash "$ROOT/skills/page-template/scripts/install.sh" --site contractor-site

# 2. (Optional) Add one or more sections under contractor-site/
mkdir -p contractor-site/2026-05-02-first-section
ROOT="$(cc-plugin-root html-showcase)"
cp "$ROOT/skills/page-template/templates/section-index.html" \
   contractor-site/2026-05-02-first-section/index.html
cp "$ROOT/skills/page-template/templates/index.html" \
   contractor-site/2026-05-02-first-section/page-a.html

# 3. Fill {{ PLACEHOLDERS }} in the HTML, then build the sitemap + nav
scripts/site.sh nav contractor-site

# 4. Validate (lychee + orphan check)
scripts/site.sh check contractor-site

# 5. View — any page reaches every other via the rail
open contractor-site/index.html
open contractor-site/site-map.html

また、インストーラーを使わず、テンプレートを手動でコピーする場合は、次のようにします。

ROOT="$(cc-plugin-root html-showcase)"
DEST=/path/to/your-site
mkdir -p "$DEST"
cp "$ROOT/skills/page-template/templates/index.html"   "$DEST/"
cp "$ROOT/skills/page-template/templates/lychee.toml"  "$DEST/"
python3 "$ROOT/skills/page-template/scripts/build-nav.py" --root "$DEST"

<repo>/scripts/ にコピーがない場合、site.sh はプラグインに同梱されている build-nav.py を使用します。そのため、インストーラーを使わなくても、プラグインに同梱されているスクリプトを直接使って、どのリポジトリからでも myhost にプッシュできます。

ほかの 3 つのスタンス（カスタマイザー、コントリビューター、パブリッシャー）については、 references/contributing.md を参照してください。Tailscale 経由で myhost に 公開する方法については、references/publishing.md を参照してください。

CDN のバージョン管理

カーネルの URL は、初期の反復作業中は @main ブランチを指定し、カーネルが安定した後はタグ付きリリースを指定します。

@main      → always-latest         → use during development; jsDelivr cache flushed automatically on each release
@v<X.Y.Z>  → immutable, content-locked → use for production-stable pages
@<sha>     → immutable, commit-locked  → use for forensic-grade pinning

リリースフローでは、各リリース後に @main のキャッシュを自動消去し、@v<X.Y.Z> のスモークテストを実施します。リリース間に @main を強制的に更新する場合（たとえば、カーネルを集中的に反復作業している間）は、cc-skills リポジトリのルートから bash tasks/release/cdn-purge を実行してください。単一のページでキャッシュを完全に回避するには、カーネルのリンクに ?v=$(date +%s) を追加してください。

自動ナビゲーションのアセット（auto-nav.css、auto-nav.js）は build-nav.py によってローカルで生成され、HTML と同じ場所に配置されます。これらは CDN から配信されません。これらの URL の ?v=N クエリ文字列もキャッシュを無効化するための設定値です。build-nav.py 内のレールの CSS または JS 本文を変更した場合は、--asset-version の値を増やしてください。

厳守事項

これらはカーネルとテンプレートに組み込まれています。破りたくなった場合は、代わりにカーネルを修正してください（references/contributing.md の Stance 3 を参照）。

• インラインの <style> ブロックは禁止です。
• HTML 要素の style="" 属性は禁止です。
• HTML にユーティリティクラスを羅列してはいけません。クラス名は意味を表すもの（.metric-card、.badge--high）とし、アトミックなもの（flex p-4 bg-blue-500）は使いません。
• カーネルが、あらゆるビジュアル上の判断における唯一の信頼できる情報源です。
• HTML はコンポーネントを配置するだけで、コンポーネントを新たに作り出すことはありません。
• ファイルシステムの構成がナビゲーショングラフそのものです。と の間のレール HTML を手作業で記述してはいけません。 構造を変更した後は、scripts/build-nav.py を再実行してください。
• 出荷済みとみなす前に、すべてのサイトが Lychee のリンクチェックと孤立ページ検出に合格している必要があります。

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ってください。

0. 自分の場所を確認する。 — 編集する前に、この SKILL.md の正式なパスを確認します。
1. 何が失敗したか？ — 指示を修正します。カーネルのコンポーネントが不足していた場合は追加します（Stance 3）。サイトマップのレールに予想外のものが表示された場合は、build-nav.py と references/sitemap.md の両方を修正します。_原則_が不明瞭だった場合は、references/principles.md を修正します。
2. 予想以上にうまくいったことは？ — 新しいセクションのパターンが繰り返し使われる場合は、カーネルコンポーネントまたは templates/section-index.html にまとめます。
3. 何にずれが生じたか？ — CDN URL の固定先、上書きの例、コンポーネントの用語、レール HTML のマーカーを、SKILL.md、テンプレート、build-nav.py の間で一致させます。
4. 記録する。 — きっかけ、修正、根拠を含む進化ログの項目を追加します。

先送りしてはいけません。次回の実行には、ここに残した状態が引き継がれます。