ppt — コードでプロフェッショナルな PPT を生成
コードで PPT を描く、テンプレートは不要：再実行可能（データを変えてスクリプトを再実行）、Git 管理可能、座標は 0.01 インチ単位で正確。WYSIWYG ではなく、Step 4 のレンダリング検証で品質を担保します。
Step 1 · 取材と文案（捏造禁止）
まず「見る人に関する 3 つの質問」に答えてから書き始める：誰に見せる？（素人 / 専門家 / 顧客）？ 観客はプロジェクトについて何を既に知っているか？ 見終わった後に何を 3 つ復唱できれば成功か？ 答えを文案の冒頭に書き、以降の取捨選択はすべてこれで判断する。
素材はプロジェクトの実際の資料（README / CLAUDE.md / docs / データバックエンド、種類に応じて選択）のみを使用する。出典のない数字は PPT に入れない；観客にとって不要な事実は本文に入れない——内部指標（関数数、API 定数、内部コード名）はデフォルトで除外。対象が専門家の場合のみ残す。
内容を掘り下げよ、名詞を並べるな：数字や機能名を拾うだけでは取材にならない。PPT の種類に応じて掘り下げる：技術・製品：設計判断＋効果比較；ポートフォリオ：作品の詳細と取捨選択；データレポート：定義とベースライン；ナラティブブランド：人物、場面、転機。
アウトラインはページごとより先に書く：取材後、まずナラティブアウトラインを書く——1 本のストーリーライン（PPT 全体で 1 つのことを論証する）＋冒頭の 3 つの回答（何か / 誰に / 何を解決するか）＋各ページが論証において果たす役割（前のページから何を受け、次のページに何を繋ぐか）。概念は説明してから使い、前方参照は禁止。2 ページ続けて繋がらない場合は並べ直す。アウトラインの下に、ページごとの文案（タイトル＋要点＋スピーチ原稿。スピーチ原稿は notes() にスピーカーノートとして入れ、紹介ビデオ制作ワークフローの原稿および現場のトーク原稿とする）を書く。タイトルは議論を深めるものであり、それぞれが独立したスローガンであってはならない。
2 段階で原稿を仕上げる：最初の段階では十分に書き込む——完全な説明形式で、観客がゼロ知識だと仮定し、「何か」「誰に」「何を解決するか」を徹底的に説明する。長くてもよい。次の段階で初めて磨き上げる——まず humanizer で味付けを薄め、次に以下の 4 つのルールに従って刈り込む。humanizer は磨き上げツールであって、初稿のテンプレートではない。初稿からその基準で書くと、説明不足でスローガンだけが飛び交う内容になる。
- 空虚な箇条書き禁止：要点には詳細を含める（機能には設計理由や効果、データには定義）。裸の名詞の羅列は削除する。
- 数字には文脈を添える：数値＋定義＋構成または比較。観客にとって意味のある数字であること。文脈のない数字をメインビジュアルにしてはいけない。
- 各ページに 3 つ以上の、出典を辿れる具体的な事実を含める；レイアウトを隠してテキストだけを読んだときに、「説明している」のであって「リストを並べている」のではない状態にする。
- スロットルール：大きな活字スロット（表紙のメインタイトル / 最終ページの大きな文字 / セクションタイトル）には、主張文またはアイデンティティ文（意見があり、声に出してスローガンになるもの）のみを置く。ドメイン名、バージョン番号、日付、統計数字はすべてサブタイトルまたはメタ情報スロットに回す。
スタイルについては、悪い決まり文句はゼロトレランス。2 層に分ける：ビジネスお決まり文句（「エンパワーメント」「クローズドループ」「ナレッジストック」「マトリックス」「エコシステム」「ワンストップ」「エンドツーエンド」など）は直接削除。技術用語（API 定数 / 内部関数名 / アーキテクチャコード / 実装詳細）は対象観客でフィルターし、素人向け PPT では削除するか、そのページで平易な言葉で説明する。数字は形容詞より優先する。タイトルは意見を述べ、名詞句にしてはいけない。ダッシュ（和文中のダブルダッシュ）は禁止。重要なプロジェクトの文案は、レイアウトの前に一度ユーザーに確認を取る。
Step 2 · デザインシステム（コードを書く前に確定し、途中で変更しない）
| 項目 | ルール |
|---|---|
| カラーパレット | プロジェクトのデザイン言語から抽出（README のビジュアル節 / サイトのメインカラー / ブランド VI）。無い場合は use_theme('warm' / 'tech' / 'forest') を使用。7+1 のクローズドシステム（7 役割＋紙白）、途中で色の追加は禁止。小さな文字の背景とのコントラスト比は 4.5:1 以上とする |
| グリッド | 16:9（13.333 × 7.5 in）・マージン 0.55・ページ番号 (12.35, 7.02)・上部に coral 色のショートバー＋セクションラベル |
| フォントサイズ | 54 表紙 / 40 大きな数字 / 30 ページタイトル / 19 カードタイトル / 13 本文 / 11 補足 / 9 注釈、中間値の使用は禁止 |
| フォント | 日本語はメイリオ。コード、ドメイン名、数字、バージョン番号はすべて Consolas |
| 密度 | 各ページに 1 つの主張。テキストが 3 行を超える場合はページ分割。表が 6 行を超える場合は行を削る |
Step 3 · 生成
pip install python-pptx -i https://pypi.tuna.tsinghua.edu.cn/simple（初回のみ）templates/primitives.py+animate.pyをターゲットプロジェクトのscripts/にコピーし、gen-<name>-deck.pyを記述する- 座標は計算式で表現する（例：
Inches(0.55 + i * 3.13)）。マジックナンバーは書かない。テキストを配置する前にcheck_fit()で事前チェックし、[FIT-WARN]が出力されたら行分割またはページ分割を行う
アニメーション（オプション；Windows + MS Office + pywin32 が必要）。デフォルトでは auto_deck() がすべてを自動処理する（表紙のカスケード / カードの float_up / 数字の zoom / リンクの wipe / テーブル行の 0.06s 高速カスケード / セクション番号の wipe up）。手動で微調整する場合のみ以下を使用：
anim = Anim(prs)
amin.auto_deck() # PPT 全体を自動編成
anim.fx(footer, 'fade', dur=0.4) # 特殊要素に追加効果
anim.chart(gf, 'series') # ネイティブチャートを系列ごとにワイプイン
P.set_transition(prs, 'fade') # 統一トランジション（morph ページは自動スキップ）
P.auto_show(prs) # スピーチ原稿に基づいた自動めくり：PPT 全体を自動再生、録画でラフカット
prs.save('deck.pptx')
anim.apply('deck.pptx') # save の後でのみ実行。COM 書き込み＋読み戻し自己検証
# 微調整：anim.stagger(P.shape_groups(s, 'card'), 'float_up', step=0.12)
# ナラティブ成長グラフ（morph の真のトゥイーン、2 ページ連続、auto は自動スキップ。有効性は EntryEffect==3954 で確認。Office 2019+、WPS は fade にダウングレード）：
P.growth_chart(prs, 6, 'Growth', 'タイトル', cats, vals, highlight=2) # 棒グラフ / 横棒グラフ
P.growth_line(prs, 8, 'Trend', 'タイトル', cats, vals, highlight=5) # 折れ線グラフ
P.growth_donut(prs, 10, 'Mix', 'タイトル', cats, vals) # ドーナツグラフ
エフェクト用語（COM で実測）：fade / wipe / appear / float_up / float_down / zoom / grow_turn / ease_in / split / wheel / stretch；1990 年代の古い効果は対象外。リズムを見栄えより優先：持続時間 0.4〜0.6 秒、カスケード間隔 0.1〜0.2 秒、1 ページあたり 2 種類以下の効果、ページ固定装飾（上部ショートバー / ページ番号 / 下部ライン）はアニメーションの対象外。データグラフは一律 growth_* を使用。ネイティブチャートは最終納品後に PowerPoint でデータを変更する場合にのみ使用する。
既存の pptx を編集する（スクリプトで編集、手動編集禁止、新しいファイル名で save）：P.deck_replace(prs, {'旧名': '新名'}) で全文置換（ノート含む）。P.deck_recolor(prs, dict(zip(P.THEMES['warm'].values(), P.THEMES['tech'].values()))) で PPT 全体のテーマカラーを変更。
ページパラダイム（辞書でありチェックリストではない：Step 1 のナラティブアウトラインに基づいてパラダイムを選択する。パラダイムのために内容を作らない。同じパラダイムを繰り返し使用しても問題ない。1 つの PPT で 9 種類のパラダイムをコレクションのように全部使うのは能力の誇示であってナラティブではない。密度は Step 1 で確保し、パラダイム自体に頼らない）：
| パラダイム | 関数 | 用途 |
|---|---|---|
| 表紙 | slide_cover | オープニング：大見出し 54 + 右縦カラーブロック |
| セクションページ | slide_section | 12 ページ以上の長尺資料のナビゲーション、雑誌風（フレームライン + 透かし番号 + 箇条書き） |
| タイムライン | slide_timeline | 進化 / ロードマップ、現在地をハイライト |
| 比較ページ | slide_versus | A/B、Before/After 比較、中央に VS ラウンドアイコン |
| 名言ページ | slide_quote | ページ全体を使う価値のある一言（12 ページ以上の PPT） |
| カード配置 | slide_cards | 並列機能 / モジュール、自動改行 |
| 数字壁 | slide_numbers | 等権の指標を一覧表示 |
| 画像テキストページ | slide_media | スクリーンショット + 要点；sidebar= で大型画像 60% + サークル注釈 + 脚注 |
| 高密度ゾーン | slide_dense | 1 ページでサブシステムを詳細に説明：メインエリア 60% + サイドエリアのグループリスト |
| 本格テーブル | slide_table | API / モデル / リスト比較、6〜9 行、列幅の階層 |
| リンク図 | slide_chain | アーキテクチャフロー、ハイライトは反転色 + サブカード |
| 2 カラムリスト | slide_rows | 技術スタック / 設定 |
| 成長グラフ | growth_chart / line / donut | データ成長グラフ（morph 真トゥイーン） |
| ネイティブチャート | bar / line / donut_chart | 納品後に PowerPoint でデータ変更が必要な場合 |
| 最終ページ | slide_closing | 連絡先；slogan= でカスタム大文字（主張文） |
Step 4 · レンダリング検証（必須、スキップ不可）
3 層パイプライン。自動化を優先し、人間は最終チェックのみ行う：
① プログラムによる一次スクリーニング：Office COM で PDF に変換（Presentations.Open 後 SaveAs("<出力>.pdf", 32)）→ python <本skill>/templates/verify.py <出力>.pdf を実行。ページ単位のオーバーフロー、プレースホルダー、コントラスト比 WCAG 準拠（72pt 以上の装飾大文字は豁免）をチェック。終了コード 1 は問題ありを示す。スクリプトを修正して再実行。
② 視覚的ブラインドレビュー：pymupdf で PNG にレンダリング（fitz + get_pixmap(dpi=100)）→ 生成コンテキストを持たないサブエージェントに 2 つの質問をする。1 つ目は各ページを 4 項目（はみ出し / 文字化け / 配置 / コントラスト）についてチェック。2 つ目は観客復唱テスト——最初の 1/3 のページだけを見せて「これは何か、誰のために、何を解決するか」と尋ね、答えられなければ Step 1 の対象読者分析か冒頭が間違っているので、文案を書き直して再生成。ブラインドレビューのプロンプトでは豁免事項を事前に想定しない（「これは意図的です」と言わない）。ページ端で切れた要素、異常に大きな低コントラスト装飾文字などの疑わしい形状も、新鮮な目で疑義として報告する。問題が見つかったらスクリプトを修正して再実行、手動での pptx 編集は禁止。
視覚的チェックでは実際の画像の絶対パスを使用し、現在のバージョンまたはハッシュを確認する。特定のツールのパス制限に遭遇した場合は互換性のあるパスを選択し、ディレクトリのコピーを固定要件としない。
③ ユーザー最終確認：前の 2 段階で機械的な問題がすべて解消された後、ユーザーは完成原稿のみを確認する。
Step 5 · 納品
報告：ページ数 + ページ一覧 / ファイルパスとサイズ / 3 層検証結果 / スピーチ原稿ページ数 / 自動再生の総時間 / 生成スクリプトの場所（再実行可能）。Git リポジトリ内にスクリプトを提出（pptx 成果物は Git 管理対象外）。
境界と注意点
- MS Office がない場合 → Step 4 では LibreOffice
soffice --convert-to pdfにダウングレード。両方ない場合 → 「視覚的検証を実施していません」と明確に報告する。 - GBK コンソール：print では非 ASCII 文字を使用せず、
OKを使う。 - pptx ネイティブテーブルの列幅が制御不能 → 一律で自前描画のテーブル行を使用（box + text を 1 行ずつ組み立てる）。
- 中国語の文字欠け → run レベルでメイリオを指定（primitives で処理済み）。
- shape_id はページごとに独立して採番され一意ではない。animate.py は XML ツリーで位置を特定しているため、二次開発ではグローバルな ID 検索をしない。pywin32：
pip install pywin32 -i https://pypi.tuna.tsinghua.edu.cn/simple。 - docx / xlsx でも primitives の考え方は流用可能だが、ページパラダイム一覧は pptx にのみ適用される。
現在のワークフローとアーカイブ
content-director が対象読者、資料の出典、ナラティブ草案を担当。PPT は編集可能なスライドの納品を目標とする。デザイン確認後に生成する。ビデオ静止画のルールは PPT に適用しない。生成スクリプト、入力データ、必要な素材とそのハッシュは recipe と共に保持する。納品リストには PPT/PDF/表紙を宣言する。アーカイブ復元チェックが完了するまではクリアしない。視覚的検証とユーザー最終確認はそれぞれ報告する。