explainer-kit

Explainer Kit

すべての解説ページで共通のデザインと仕組みを提供します。explain-with-* スキルが何を表示するかを決め、このキットがどのように見せるか、各パーツをどのように組み合わせるかを決めます。これにより、すべての解説ページで一貫性が保たれ、エージェントが CSS、色、プレーヤーを独自に考案する必要がなくなります。

このスキルを使う場面

• explain-with-* スキル（ストーリーテリング、コードのウォークスルー、プレビュー、セクション動画、スライド、動画）を使ってチャプターを作成するとき。
• explain-visually 用に、複数のチャプターを1つのページにまとめるとき。
• 解説ページのテーマを変更するとき、または共通コンポーネントを追加するとき。

ファイル

すべてこのファイルと同じ階層の assets/ にあります。

ファイル	内容
FRAGMENT-CONTRACT.md	各フラグメントが従うルールと、コンポーネントの早見表です。フラグメントを書く前にお読みください。これが API の全容です。
SCRIPTS-AND-TABS.md	独自のスクリプトがあるフラグメント（動画、スライド、コードのウォークスルー）とタブ付きページでのみ使用します。
assemble.py	概要とフラグメントから最終ページを構築し、コントラクトを検証します。
preview.py	JSON から選択肢（オプション）または変更前後のチャプターを生成します。
check.py	デスクトップとスマートフォンで組み立てたページを開き、修正が必要な項目だけを一覧表示します。
kit.css、kit.js、shell.html	アセンブラーがインライン化するスタイル、動作、ページテンプレートです。ページを書く際に読む必要はありません。

テーマ

• テーマは4種類あります。Violet（デフォルト。ダークを優先し、ほぼ黒に紫のアクセントを1色、Geist フォントを使用）、Ocean、Amber、Aurora です。それぞれライト版やダーク版が用意されています。閲覧者はテーマを切り替えることができ、選択内容は記憶されます。
• 初回読み込み時のテーマは assemble.py --theme で選択します。ページごとのカラーパレットやフォントは追加しないでください。
• 色、フォント、角丸は必ず var(--ev-…) トークンから取得してください。ページはすべてのテーマとライトモード、ダークモードで動作する必要があるため、値を直接指定してはいけません。
• セマンティックカラーには固定の意味があり、必ずグリフを伴います。新規 +、削除 −、リスク !、判断 ◆、問題なし ✓ です。アクセントは「ここが要点」を示すものであり、ステータスを示すものではありません。

ページの構築方法

1. 各チャプターは1つのフラグメントです。<section class="ev-tab-content" data-tab="NAME"> を1つだけ使い、スコープを限定した独自の <style> と、EV.onShow(NAME, …) 内で構築する IIFE <script> を含めます。
2. コーディネーターが概要（<header class="ev-overview">）を作成します。内容は、アイブロウ、答えを明示する見出し、1文、主役となるビジュアル、最大1つの「判断」コールアウトを含む重要な一文です。情報ボックスのグリッドは使いません。
3. assemble.py がキットをインライン化し、概要とフラグメントを挿入します。フラグメントがコントラクトに違反している場合、ページの書き込みを拒否します。

# One scrollable page with a sticky chapter list (default for explain-visually)
python assets/assemble.py --page --toc --title "Short name" --overview overview.html \
  --section story=frag-story.html --section code=frag-code.html --section decide=frag-decide.html \
  --out index.html

# One fragment on its own page
python assets/assemble.py --standalone frag-slides.html --title "Short name" --out index.html

• --section NAME=FILE の NAME は、フラグメントの data-tab と一致している必要があります。
• チャプターの見出しを設定するには、フラグメントの <section> に data-label、data-hint、data-part-title、data-part-lede を指定します。チャプター一覧に項目を表示するには、要素に id と data-toc="短いラベル" を指定します。
• 出力は、アーティファクトとして公開できる自己完結型の HTML ページです。

すべてのチャプターに共通するルール

• まず簡潔にまとめます。要点を示す見出し → 具体的なビジュアル1つ → 短い文を最大2～3文 → 詳細の順にします。
• 詳細は ev-more のトグルの中に配置し、要約では内容を明示します（例：「ティックの軌跡・5行の理由」）。「More」や「Show details」だけを表示してはいけません。
• 詳細も視覚的に表現します。コード行の強調表示、差分のガター、グループ、ステータスチップ、コンパクトな表、小さな棒グラフなどを使います。
• 画面に表示されている間、読むことを意図したテキストを薄くしたり、隠したりしてはいけません。
• 動きは何かを説明する場合にのみ使い、そうでなければ削除します。prefers-reduced-motion を尊重し、停止状態でもページの内容をすべて把握できるようにします。
• すべてを1ページにまとめます。1つのアーティファクト内で、別々のページへのリンクを作成してはいけません。

キットの変更

• キットの変更は、ユーザーから依頼された場合に限ります。1ページの構築中に変更してはいけません。ページではキットをそのまま使用します。
• 新しいコンポーネントは kit.css／kit.js と FRAGMENT-CONTRACT.md の早見表に ev- プレフィックスを付けて追加します。その後、既存のページに対して assemble.py と check.py を再実行します。