pptx-slides

PPTX スライド — プログラムによる PowerPoint 生成

PptxGenJS（Node.js）を使用して、プロ品質で編集可能な PowerPoint プレゼンテーションを生成します。正確なレイアウト、テキスト測定、重なり検証を備えた OOXML 準拠の .pptx ファイルを作成します。

同梱ヘルパー

すべての PPTX 生成スクリプトでは、bun を介して同梱の TypeScript ヘルパーモジュールをインポートします。

import pptxgen from 'pptxgenjs';
import * as h from '${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts';
const pptx = new pptxgen();
pptx.layout = 'LAYOUT_16x9'; // 10" × 5.625"

生成スクリプトは bun で実行します（ビルド手順は不要です）。

npx -y bun ${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts theme list

依存関係（skia-canvas、fontkit、linebreak、prismjs）は初回実行時に bun によって自動インストールされます。手動でインストールする必要はありません。

モジュールの概要

モジュール	主なエクスポート	目的
text	autoFontSize()、calcTextBoxHeightSimple()、scale()	skia-canvas を使用したフォントを考慮したテキスト測定、適応型サイズ調整
theme	createTheme()、PRESETS、sectionBackground()	12 種類の厳選されたプリセットを備えたデザイントークンシステム
layout	warnIfSlideHasOverlaps()、alignSlideElements()、distributeSlideElements()	重なり検出、境界チェック、配置
layout_builders	addFeatureGrid()、addCardRow()、addTimeline()、addMetricsRow()、addComparisonTable()	高レベルのコンポーネントビルダー
decorative	addStaircase()、addSectionBadge()、addProgressBar()、addSlideNumber()	ビジュアルに個性を加える要素
validation	validateDeck()	保存前の品質検証を一括実行
code	codeToRuns()	Prism.js の構文ハイライトを PptxGenJS のテキストランに変換
image	getImageDimensions()、imageSizingCrop()、imageSizingContain()	画像のバイナリデータからの寸法検出とアスペクト比に応じたサイズ調整
svg	svgToDataUri()	SVG のサニタイズと Base64 データ URI エンコード
util	safeOuterShadow()、normalizeColor()、inchesToEmu()	影効果、色と単位の変換

テーマの選択

厳選されたプリセットを選ぶか、カスタムテーマを作成します。

// Use a preset
const theme = h.createTheme(h.PRESETS.darkMonospace);

// Or customize
const theme = h.createTheme({
  accent: 'ff6b35',
  font: { heading: 'Poppins', body: 'Inter' },
});

使用可能なプリセット：darkMonospace、swissModern、boldSignal、darkBotanical、cleanCorporate、neonCyber、warmMinimal、vintageEditorial、terminalGreen、gradientWave、midnightBlue、paperInk。

背景が混在するデッキでは、セクションマップを定義します。

const sectionMap = { '0': 'brand', '1-3': 'light', '4-8': 'default' };
const colors = { brand: theme.accent, light: theme.bg.secondary, default: theme.bg.primary };
slide.background = { color: h.sectionBackground(slideIndex, sectionMap, colors) };

適応型フォントサイズ

ハードコードしたフォントサイズの代わりに scale() を使用します。これは PPTX における CSS の clamp() に相当します。

const titleSize = h.scale(theme.size.title.min, theme.size.title.max, { bullets: 0, textLength: title.length });
const bodySize = h.scale(theme.size.body.min, theme.size.body.max, { bullets: 5, textLength: 800 });

テキストボックスに正確に収めるには、skia-canvas による測定を使用する autoFontSize() を使います。

const opts = h.autoFontSize('Long paragraph text...', 'Arial', { w: 8, h: 3, minFontSize: 14, maxFontSize: 28 });
slide.addText(text, { x: 1, y: 1.5, ...opts });

生成ワークフロー

1. レイアウトを計画する — コンテンツの概要を references/slide-patterns.md のスライドタイプに対応付けます
2. テーマを選択する — プリセットを選ぶか、カスタムのテーマトークンを定義します
3. スライドを生成する — addFeatureGrid()、addCardRow() などのヘルパーを使用して作成します
4. 検証する — 保存前に h.validateDeck(pptx) を実行します
5. 問題を修正する — 検証レポートに基づいて調整し、再検証します
6. 納品する — すべてのコンテンツスライドに発表者ノートを付けて .pptx ファイルを提供します

基本的なデザインルール

タイポグラフィ

• 本文の最小サイズ：18pt（24～28pt を推奨）。適応型サイズ調整には scale() を使用します。
• タイトルの文字サイズ：36～44pt
• キャプション／脚注：最小 14～16pt（絶対的な下限：14pt）
• フォントファミリー：適切なフォールバックチェーンを使用するため、h.resolveFont(theme, 'heading') を使います

レイアウト

• スライドの寸法：10" × 5.625"（ワイドスクリーン 16:9）
• セーフマージン：すべての端から 0.5"（theme.spacing.margin）
• ホワイトスペース：各スライドの 40～50% を空白にすることを目指します
• 配置：正確に配置するには、h.alignSlideElements() と h.distributeSlideElements() を使用します

色とアクセシビリティ

• コントラスト比：WCAG AA の最小基準（本文 4.5:1、大きな文字 3:1）
• 色覚多様性への配慮：データ可視化には Wong または IBM のパレットを使用します
• テーマトークン：常に theme.text.primary、theme.accent を使用し、色をハードコードしないでください

検証ワークフロー

各デッキの保存前に h.validateDeck(pptx) を実行します。次の項目を確認します。

• 各スライド上の要素の重なり
• スライドの境界内に要素が収まっていること
• フォントサイズが最小 14pt 以上であること
• スライドごとの箇条書き数（最大 6 件）
• 発表者ノートの有無

アンチパターン

• どこであっても、14pt未満のテキストを使用する
• 1枚のスライドに7個以上の箇条書きを配置する
• スライドの境界からはみ出す要素を配置する
• テーマトークンの代わりに色をハードコードする
• scale() または autoFontSize() の代わりにフォントサイズをハードコードする
• 保存前に validateDeck() を実行しない
• コンテンツスライドにスピーカーノートがない
• PptxGenJS の fit または autoFit を h.autoFontSize() の代わりに使用する

編集可能性に関するガイダンス

受け取った人がデッキを編集できるよう、編集可能性を考慮して設計してください。

• ネイティブのテキストボックス — クリックして直接編集できます。テキストを画像に変換して固定しないでください。
• 関連する要素をグループ化する — カードレイアウトをひとまとまりとして移動できます。
• ネイティブの図形 — 可能な限り、埋め込み SVG の代わりに角丸長方形、円、線を使用します。
• スピーカーノート — 各コンテンツスライドで slide.addNotes('...') を使って要点を追加します。
• マスターレイアウト — テンプレートデッキでは、一貫性のある新しいスライドを作成できるよう、スライドレイアウトを定義します。

図形を使ったアーキテクチャ図

画像ではなく、PptxGenJS のネイティブ図形を使ってアーキテクチャ図を作成します。

• サービス／コンポーネントには長方形を使用します：slide.addShape('rect', { ... })
• 接続には線と矢印を使用します：slide.addShape('line', { ... })
• 色分け：アクティブなコンポーネントには theme.accent を、非アクティブなコンポーネントには theme.text.secondary を使用します。
• 段階的な提示：同じ図を2～3枚のスライドにわたって作成し、徐々に複雑にしていきます。

参考ファイル

• references/pptxgenjs-helpers.md — バンドルされたヘルパーモジュールの完全な API リファレンス
• references/slide-patterns.md — 寸法と配置を含む、スライドタイプ別パターンの詳細

スクリプトファイル

• scripts/main.ts — TypeScript CLI のエントリーポイントとライブラリの再エクスポート（npx -y bun で実行）
• scripts/types.ts — すべてのヘルパーモジュールで共有する TypeScript インターフェース
• scripts/theme.ts — createTheme() と resolveFont() を備えた、厳選された12種類のテーマプリセット
• scripts/text.ts — skia-canvas によるフォント対応のテキスト測定、autoFontSize()、scale()
• scripts/layout.ts — 重なりの検出、要素の整列、境界チェック
• scripts/layout_builders.ts — addFeatureGrid()、addCardRow()、addTimeline() など
• scripts/decorative.ts — addStaircase()、addSectionBadge()、addProgressBar()
• scripts/validation.ts — 保存前の品質検証を行う validateDeck()
• scripts/code.ts — Prism.js による構文ハイライトを PptxGenJS のテキストランに変換
• scripts/image.ts — バイナリの寸法検出とアスペクト比に基づくサイズ調整
• scripts/svg.ts — SVG のサニタイズと Base64 データ URI のエンコード
• scripts/util.ts — 影の効果、色の正規化、単位変換