HTML Guide

⚠️ 画像確認時は 00_SYSTEM/共通ルール/画像読込運用規約.md 準拠（Read base64廃止・browser_snapshot/ビューポート分割/別窓1枚）

スキル: html-guide — ガイドサイト用インタラクティブHTMLページ作成

トリガーワード

• 「新しいHTMLページを作って」
• 「インタラクティブな章を追加したい」
• 「HTML章を追加して」
• /html-guide

概要

ガイドサイト（claude-code-guide / loop-engineering-guide 等）に新しいHTMLページを追加する際のルールを自動適用するスキル。 CSS変数・ダーク/ライトモード対応・視認性チェック・CIテスト通過を保証する。

適用範囲: convert.py パイプラインを持つ repo（claude-code-guide: docs/chapters/）と、 手書きHTMLの repo（loop-engineering-guide: ルート *.html）の両方に対応する。 各 repo の構造差は Step 2 と Step 5 で吸収する。

実行手順（Claude Code が行うこと）

Step 1: 要件確認

ユーザーに以下を確認する:

• 章番号・タイトル・概要
• インタラクティブ要素の有無（クリック・アニメーション等）
• 特殊なレイアウト要件

Step 2: HTMLファイル作成

以下のテンプレートをベースに作成する。配置場所は repo により異なる:

# claude-code-guide（convert.py パイプライン型）: source Markdown → 変換で生成
~/projects/claude-code-guide/docs/src/XX_タイトル.md   # source

# loop-engineering-guide（手書きHTML型）: ルートに直接HTML
~/projects/loop-engineering-guide/XX-slug.html

必須チェックリスト（作成時に必ず守ること）:

✅ CSS変数ルール

/* ✅ 正しい: CSS変数を使う */
color: var(--text, #1e293b);
background: var(--bg-card, #ffffff);

/* ❌ 禁止: ハードコード色 */
color: #1e293b;
background: white;

使用すべきCSS変数一覧:

✅ CSS変数の使用前検証（重要・文字消失バグの直接防止）

上記一覧にない変数を使う場合、必ず定義を確認してから使う。 一覧表は「よく使う変数」の掲示にすぎず、 未定義変数（例: --fg, --bg-raised）を書いても作成時には気づけない。これがダークモードで文字が消える主原因。

ルール:
1. var(--xxx) を使うなら、xxx が assets/style.css の :root か [data-theme="..."] に
   定義されているか grep で確認（インライン <style> に定義する場合も可）。
2. 新しい変数が必要なら、assets/style.css の :root（ライト）と [data-theme="dark"]（ダーク）
   の【両方】に定義を追加してから使う。片方だけだとモード切替で文字が消える。
3. fallback を付ければ文字消失は起きない（var(--xxx, #fff)）が、未定義変数の使用自体は
   CI（test_convert.py / test_css.py）で fail する。基本は定義してから使う。

# 使おうとしている変数が定義済か確認（claude-code-guide の例）
grep -E '^\s*--fg' ~/projects/claude-code-guide/assets/style.css
# 何も出なければ未定義 → 変数名を確認 または 定義を追加

✅ コマンドバッジのルール

/* ✅ コマンドバッジ（/init のような表示）*/
.cmd-badge {
    background: var(--accent-bg, #eef2ff);
    color: var(--accent-dark, #4f46e5);
    font-family: monospace;
    font-weight: 700;
    padding: 0.25rem 0.6rem;
    border-radius: 6px;
}
/* ❌ code-bg は濃い紺色なので文字が消える */
background: var(--code-bg);  /* 禁止 */

✅ インラインコードのルール

/* ✅ インラインコード */
code {
    background: var(--bg-secondary, #e8edf5);
    color: var(--text, #1e293b);
    padding: 0.1rem 0.35rem;
    border-radius: 4px;
}

✅ ダーク/ライト両モード対応

カスタムスタイルに [data-theme="dark"] セレクタが必要な場合:

.my-element { background: #e8f5e9; color: #2e7d32; }
[data-theme="dark"] .my-element { background: #1b3d1e; color: #a5d6a7; }

✅ 禁止文字列（テストで検出される）

HTMLに以下の文字列を含めない:

• yn4416（Linuxユーザー名）
• fukukei（GitHubアカウント名、公開URLを除く）
• GLM-5.3, GLM-5.1, GLM-4.7, GLM-4.5-Air（モデル名）
• 00_SYSTEM/（SSOTの内部パス）
• glm_ask, minimax_ask（MCPツール名）

Step 3: index.html に章を追加

# Python で安全に挿入
python3 -c "
with open('docs/index.html', 'r') as f: content = f.read()
old = '        </section>'  # 最後の </section> の直前
new = '''            <a href=\"chapters/XX-slug.html\" class=\"chapter-card\">
                <div class=\"card-icon\">🎯</div>
                <div class=\"card-number\">第XX章</div>
                <h2 class=\"card-title\">タイトル</h2>
                <p class=\"card-desc\">説明</p>
            </a>

        </section>'''
# 最後の出現のみ置換
idx = content.rfind(old)
content = content[:idx] + new + content[idx+len(old):]
with open('docs/index.html', 'w') as f: f.write(content)
print('OK')
"

Step 4: 前後章のナビゲーションリンクを更新

作成したHTMLの章ナビ（chapter-nav-bottom）と、前の章のHTMLの「次の章→」リンクを更新する。

Step 5: テスト実行（CIでデプロイをガード）

repo ごとのテストファイルを実行する。両 repo とも「未定義CSS変数検出（文字消失防止）」と 「禁止文字列検出（個人情報）」をCI（static.yml）で実行し、fail するとデプロイが阻止される。

# claude-code-guide（convert.py パイプライン型）
cd ~/projects/claude-code-guide
python3 -m pytest test_convert.py -q

# loop-engineering-guide（手書きHTML型）
cd ~/projects/loop-engineering-guide
python3 -m pytest test_css.py -q

テストが未定義CSS変数で fail した場合: 変数名が正しいか / 定義を追加すべきか見直す（Step 2「CSS変数の使用前検証」参照）。絶対にテストを無効化しない。

全テストが通ることを確認してからコミットする。

Step 6: コミット＆プッシュ

git add -f docs/chapters/XX-slug.html docs/index.html
git commit -m "feat: 第XX章「タイトル」追加 ..."
git push origin main

注意: docs/ は .gitignore に含まれているため git add -f が必要。

よくある問題と対処

ファイル場所

claude-code-guide（convert.py パイプライン型）:

• ソースMarkdown: ~/projects/claude-code-guide/docs/src/
• 生成HTML: ~/projects/claude-code-guide/docs/chapters/
• インデックス: ~/projects/claude-code-guide/docs/index.html
• スタイル変数の参照: ~/projects/claude-code-guide/assets/style.css
• テスト: ~/projects/claude-code-guide/test_convert.py（未定義変数検出 + 禁止文字列 + XSS/構造）

loop-engineering-guide（手書きHTML型）:

• HTML（手書き）: ~/projects/loop-engineering-guide/*.html
• スタイル変数の参照: ~/projects/loop-engineering-guide/assets/style.css
• テスト: ~/projects/loop-engineering-guide/test_css.py（未定義変数検出）