ppt-design-skill

PPT デザインスキル

セットアップ（初回）

このスキルが呼び出す pptx ツール群（scripts/office/*、add_slide.py、clean.py、thumbnail.py）はこのリポジトリには含まれていません（ライセンスにより再配布が禁止されています）。初回使用の前に、上流リポジトリから一度取得してください。

python3 scripts/setup_upstream.py           # no-op when already installed
python3 scripts/setup_upstream.py --check   # verify installed

スクリプトでは再現性を確保するため、上流のコミットを固定しています（変更するには --ref を指定します）。また、upstream/SKILL.md（デザインアイデアの参考資料）と、取得したファイルに適用される上流の LICENSE.txt も取得します。取得したツールに必要な Python 依存関係：pip install defusedxml lxml Pillow "markitdown[pptx]"。

クイックリファレンス

タスク	ガイド
コンテンツの読み取り／分析	python -m markitdown presentation.pptx
テンプレートから編集または作成	editing.md を読む
ゼロから作成	計画 → 生成 → QA（下記「ゼロから作成」を参照）
デザインの決定（ナラティブ／テンポ／適応）	references/design-playbook.md を読む
デザインテーマとレイアウト	design-system.md を読む
テーマトークン（一覧／検証／抽出）	python3 scripts/theme.py list ＋ references/custom-themes.md
決定論的 QA ゲート	scripts/qa/（オーバーフロー／コントラスト／余白／トークン／フォント、stdlib のみで独立動作）
アウトラインゲート（計画のゲート）	python3 scripts/qa/outline_check.py outline.json ＋ references/outline-schema.md
モジュール式スライドデッキ（15 ページ以上）	python3 scripts/scaffold_deck.py outline.json --out-dir deck --theme <name> ＋ references/modular-decks.md

---

コンテンツの読み取り

# Text extraction
python -m markitdown presentation.pptx

# Visual overview
python scripts/thumbnail.py presentation.pptx

# Raw XML
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" presentation.pptx

---

編集ワークフロー

詳細は editing.md を読んでください。

1. thumbnail.py でテンプレートを分析します
2. 抽出 → 構造変更（add_slide.py／<p:sldIdLst>／clean.py）→ コンテンツを編集 → zip 化 → validate.py --original

---

ゼロから作成

作成ワークフロー（3 段階、順序は固定）：

Step 1 · 計画（必須、省略禁止）

references/design-playbook.md を読んでください — ナラティブアーク、ページ計画表、明暗のリズム、レイアウト決定ツリー、適応ルール、中国語組版、密度管理。

テーマを選ぶ：python3 scripts/theme.py list（組み込み 9 セット ＋ プロジェクトの ./ppt-themes/ ＋ ユーザーレベル）。プロジェクトまたはユーザーレベルのテーマが見つかった場合は、優先して使用するかユーザーに確認します。ユーザー提供のブランドカラーがある場合は、references/custom-themes.md の抽出手順を使用します。

ページ計画表（ページ番号 → レイアウト → 明暗 → コンテンツの形状 → 視覚要素）を作成し、outline.json にまとめて、計画ゲートを通過してからコードを書きます。

python3 scripts/qa/outline_check.py outline.json   # exit 0=PASS；主题名/版式 id/多样性/连续重复全查

スキーマと登録済みレイアウト ID については、references/outline-schema.md を参照してください。ゲートに通らない場合は、まず outline.json を修正します。計画段階なら 1 行の変更で済みますが、コーディング段階では 1 ページ分の手戻りになります。

Step 2 · 生成

API の詳細と破損に関する注意点は pptxgenjs.md を読んでください。

• テーマと配色：design-system.md（9 テーマ、安全なフォントのみ使用）
• レイアウトコード：雑誌風 templates/layouts/magazine-layouts.md ／ スイス風 templates/layouts/swiss-layouts.md ／ 分析モデル templates/layouts/analysis-models.md（SWOT／PEST／キャンバス／ダブルダイヤモンド／競争ポジショニング）
• コンポーネントのレシピ：templates/components.md
• スイス風の厳格な制約：references/swiss-layout-lock.md
• 15 ページ以上はモジュール式パイプラインを使用：python3 scripts/scaffold_deck.py outline.json --out-dir deck --theme <name> を実行して slide-NN.mjs ＋ compile.mjs を生成します。契約とサブエージェントによる並列作業については references/modular-decks.md を参照してください。

Step 3 · QA

決定論的ゲート（最初に実行し、すべて PASS してから視覚チェックに進みます。exit 0=PASS／1=違反あり。CI に組み込めます）：

python3 scripts/qa/cjk_overflow_check.py output.pptx   # 文字溢出/越界（CJK 1em·半角 0.5em 估宽）
python3 scripts/qa/contrast_check.py output.pptx       # WCAG 对比度（4.5:1 正文 / 3:1 大字）
python3 scripts/qa/token_check.py slides/*.mjs --theme ink-classic  # 主题 token 门禁（硬编码色/字体即 fail）
python3 scripts/qa/font_check.py output.pptx                        # Office 安全字体 + 本地可用性（fc-list）
pdftoppm -png -r 150 output.pdf slide \
  && python3 scripts/qa/edge_check.py slide-*.png      # 渲染后边缘裁切/空页（纯 stdlib，PNG）

5 つのスクリプトはすべて stdlib のみを使用し、単独で解析します（上流から取得したファイルには依存しません）。その後、references/checklist.md の P0〜P3 に従ってチェックします（下記の QA 節を参照）。

---

デザインのアイデア

デザインアイデアの完全なチェックリスト — インスピレーションを得るための配色、タイポグラフィのルール、余白、よくある間違いの一覧は、セットアップ時に取得される上流リファレンスにあります。scripts/setup_upstream.py を実行した後、上流の upstream/SKILL.md（§ デザインのアイデア）を読んでください。以下のセクションは、このリポジトリ独自のデザインシステムを重ねたものです。

基本原則（簡易版）：

• デッキ全体を支えるメインカラーを1色決め、アクセントは鮮明に、使用は控えめにします
• タイトルスライドと締めくくりのスライドは暗い背景、コンテンツスライドは明るい背景にします。高級感を出す場合は、全体を暗い背景にします
• ビジュアルモチーフを1つ選び、すべてのスライドで繰り返し使用します
• すべてのスライドに、少なくとも1つの視覚要素（画像、グラフ、アイコン、図形）を入れます。テキストだけのスライドは作りません
• デッキ全体でレイアウトに変化をつけ、同じレイアウトを3枚を超えて連続使用しません

デザインシステム クイックスタート

事前構築済みテーマとレイアウト座標については、design-system.md を参照してください。次の内容が含まれています。

• 組み込みテーマ9種類（マガジン5種類＋スイス4種類）と、そのまま使える PptxGenJS 用カラー設定
• レイアウトテンプレート32種類 — 完全なコードは templates/layouts/（マガジン10種類＋スイス22種類）を参照してください
• マガジン（セリフ）とスイス（サンセリフ）の各スタイルに対応したOffice で安全なフォントの組み合わせ

まず計画を立てる：コードを書く前に references/design-playbook.md を読み、ページ計画表を作成してください。レイアウト座標は基準であり、制約ではありません。プレイブック第4節の適応ルールに従って調整してください。

7つの確認質問（ユーザーのアイデアが漠然としている場合に推奨される任意のベストプラクティス）：

1. 対象者と用途：ロードショー／社内共有／技術発表／ポートフォリオ／学術発表のどれですか？
2. 所要時間とページ数：スライドは10～12枚／15～20枚／25枚以上のどれですか？
3. 既存資料：文書／リンク／古い PPT／データ／画像はありますか？
4. テーマの選択：以下の組み込みテーマを参照してください。マガジン（エレガント／人文的）とスイス（ミニマル／合理的）のどちらですか？
5. 好みのスタイル：温かみのある色調のセリフ体タイトル、またはコントラストの強いアクセントカラーを使ったサンセリフ体のどちらですか？
6. 言語：中国語／英語／二か国語のどれですか？
7. 納品物：PPTX のみ／カバー画像も必要／Web 版も必要のどれですか？

スタイルギャラリーのテクニック（humanize-ppt を参考）：ユーザーがテーマ選びに迷っている場合は、やみくもに選ばず、候補となるテーマを2～4種類使ってカバーを1枚ずつレンダリングし、ユーザーに選んでもらってからデッキ全体を作成してください。

テーマの使用リズム：

Cover       →  Main theme (consistent across deck)
Section     →  Same theme, variant switch (light/dark)
Data page   →  Same theme, light variant
Highlight   →  Same theme, dark variant
Closing     →  Same theme, dark variant or cover style

ルール：デッキの途中で別のテーマに切り替えてはいけません。

組み込みデザインシステムのテーマ

組み込みテーマ9種類（マガジン5種類＋スイス4種類）の完全な色指定と適用シーンについては、design-system.md を参照してください。テーマ名がそのままトークンです：ink-classic / indigo-porcelain / forest-ink / kraft-paper / dune / swiss-blue / swiss-yellow / swiss-green / swiss-orange（プロジェクト／ユーザーレベルのテーマは python3 scripts/theme.py list で確認してください）。

組み込みレイアウトテンプレート

座標は design-system.md に、完全なコードは templates/layouts/ にあります — マガジン10種類、スイス S01～S22、分析モデル5種類（SWOT／PEST／キャンバス／ダブルダイヤモンド／競合ポジショニング）。outline.json ではこれらの登録済み ID を参照してください（全一覧は references/outline-schema.md を参照）。レイアウトの多様性と連続使用の上限は、計画段階で outline_check.py によって強制されます。

中国語対応の安全なフォント（組み込みテーマで指定済み）

Office で安全なフォントのみを使用してください——ユーザーのマシンにないフォント（Inter／Playfair／Noto シリーズ）は、宋体にフォールバックします。組み込みテーマの中英語フォントの組み合わせ（マガジンのセリフ体／スイスのサンセリフ体）は design-system.md で指定済みです。テーマトークンをそのまま使用し、独自のフォントの組み合わせは作らないでください（font_check.py でチェックされます）。

---

QA（必須）

問題があることを前提にしてください。問題を見つけるのがあなたの役割です。

最初のレンダリングが正しいことは、ほとんどありません。確認作業ではなく、バグ探しとして QA に取り組んでください。最初の確認で問題が1つも見つからなかったなら、十分に注意深く見ていません。

コンテンツ QA

python -m markitdown output.pptx

コンテンツの欠落、誤字、順序の誤りを確認します。

テンプレートを使用する場合は、プレースホルダーテキストが残っていないか確認してください：

python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"

grep で結果が返ってきた場合は、成功と判断する前に修正してください。

ファイル QA

python scripts/office/validate.py output.pptx                      # built from scratch
python scripts/office/validate.py output.pptx --original src.pptx  # built from a template

デッキがテンプレートから作成された場合は、必ず --original を渡してください — これにより、テンプレート自体の不具合が自分の不具合として扱われないよう、テンプレートを基準にスキーマ／スライドのチェックが行われます。

ビジュアル QA

⚠️ サブエージェントを使ってください — スライドが2～3枚でも同様です。コードを見続けていると、実際にあるものではなく、期待するものが見えてしまいます。サブエージェントなら新鮮な目で確認できます。

スライドを画像に変換し（画像への変換を参照）、すぐに使える確認用プロンプトをreferences/checklist.md §「子代理看图提示词」からサブエージェントに送ってください。スライドごとに重なり、はみ出し、衝突、隙間、コントラスト、残っているプレースホルダーを確認し、軽微なものを含めたすべての問題を報告します。

出荷前チェックリスト

成功を宣言する前に、references/checklist.md（P0～P3レベル）を確認してください。納品前にP0をすべてクリアする必要があります：プレースホルダーテキストがないこと、はみ出しや切れがないこと、要素の重なりがないこと、テーマに一貫性があること、最小フォントサイズを満たしていること。

検証ループ

1. スライドを生成 → 画像に変換 → 確認
2. 見つかった問題を列挙（何も見つからなかった場合は、もう一度、より厳しく確認します）
3. 問題を修正 — 失敗パターンのカタログに記載された修正順に従います：内容 → 構造 → レイアウト → スタイル。スタイルから修正を始めないでください
4. 影響を受けたスライドを再検証 — 1つの修正が別の問題を引き起こすことはよくあります
5. 新しい問題が見つからない状態で全体の確認を完了するまで繰り返します。最大3ラウンドです。3ラウンド後もP0の問題が残る場合は、残っている問題をユーザーに伝え、無限に再試行しないでください。

少なくとも1回、修正と検証のサイクルを完了するまでは、成功を宣言しないでください。

---

デザインシステムのリファレンス

ドキュメント	内容
design-system.md	組み込みテーマ9種類（雑誌風5種類＋スイス風4種類）、レイアウト座標のクイックリファレンス、安全なフォントの組み合わせ
references/design-playbook.md	デザイン意思決定ハンドブック：物語の弧、ページ計画表、明暗のリズム、レイアウトの意思決定ツリー、適応ルール、中国語組版、密度管理（コードを書く前に必読）
templates/themes/magazine-themes.md	雑誌風テーマ5種類の色の詳細
templates/themes/swiss-themes.md	スイス風テーマ4種類の色の詳細
templates/layouts/magazine-layouts.md	雑誌風レイアウト10種類 — PptxGenJSの完全なコードとバリエーション（正式版）
templates/layouts/swiss-layouts.md	スイス風レイアウト22種類（S01～S22）— PptxGenJSの完全なコード（正式版）
templates/layouts/analysis-models.md	ビジネス分析レイアウト：SWOT／PEST／ビジネスモデルキャンバス／ダブルダイヤモンド／競争ポジショニング
templates/components.md	コンポーネントのレシピ集（統計カード、コールアウト、アイコン行、チャート、クローム）
references/checklist.md	P0～P3品質チェックリスト（.pptx専用）
references/outline-schema.md	outline.jsonの計画ゲート：スキーマ、登録済みレイアウトID、チェックルール
references/image-prompts.md	画像生成プロンプトガイド
references/screenshot-framing.md	スクリーンショット適応仕様
references/swiss-layout-lock.md	登録済みスイス風レイアウト22種類、厳格な制約

---

画像への変換

プレゼンテーションを個々のスライド画像に変換して、視覚的に確認します：

python scripts/office/soffice.py --headless --convert-to pdf output.pptx
pdftoppm -jpeg -r 150 output.pdf slide

これにより、slide-01.jpg、slide-02.jpgなどが作成されます。

修正後に特定のスライドを再レンダリングするには：

pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed

---

依存関係

• 初回実行時：python3 scripts/setup_upstream.py — ツールのランタイムを取得します（セットアップを参照）
• pip install "markitdown[pptx]" - テキスト抽出
• pip install Pillow defusedxml lxml - サムネイル一覧／検証
• npm install -g pptxgenjs - ゼロからの作成
• LibreOffice（soffice）- PDF変換（サンドボックス環境向けに scripts/office/soffice.pyを介して自動設定）
• Poppler（pdftoppm）- PDFから画像への変換