design-export-repair

デザインのエクスポートを修復する

AI で生成されたスライド／PDF のエクスポートを修正します（Claude Design のエクスポート経路向けに構築されていますが、チェック内容は Claude 固有ではなく、一般的な OOXML／PDF の品質管理です）。アプリ内では問題なく見えても、エクスポート後に崩れることがあります。たとえば、テキストの末尾数文字が欠ける、フォントが元のデザインと一致しない、PowerPoint では問題なく開けるのに、一部の変換ツールでは処理できない .pptx などです。

実際の破損したエクスポートを検証し、4 種類の不具合を特定して修正しました。それぞれの確認方法や修正によるトレードオフを含む詳細は、references/defect-classes.md を参照してください。このスキルを未対応のケースに拡張する前に、内容を確認してください。特に、同ファイルにある不具合 #4 は、「図形の形状が正しく見える」ことと「レンダリングされた PDF が正しく見える」ことは同じではない、という好例です。新たな問題の報告を形状の問題だと決めつける前に、一読する価値があります。

エンドツーエンド：Claude Design からきれいなファイルまで

これは Claude Code を実行する人向けに書かれたもので、Claude だけを対象にしたものではありません。実際に何をすればよいか把握するため、一度ざっと目を通してください。Design プロジェクトを Claude Code に渡す方法は 2 つあり、それぞれ動作が異なります。

方法 A — 通常のエクスポート（「デッキ／PDF が壊れて見える」というケースに合う方法です）： Claude Design でエクスポートを使い、PDF、PPTX、または HTML を選びます。ファイルを保存し、使用している Claude Code に渡します。環境が対応していればチャットに添付し、そうでなければディスクに保存して Claude にパスを伝えてください。その後、Claude にこのスキルを使うよう指示します。「PDF にエクスポートするとこのデッキが壊れて見えるので、修正してもらえますか」のような自然な言い方だけで十分です（このスキルの説明は、その表現に合うように書かれています）。明示したい場合は、スキル名（design-export-repair）を直接指定してください。

方法 B — 「Claude Code に送信」ボタン。 これは通常のエクスポートとは関連がありますが、別の機能です。デッキのエクスポート修正ではなく、コードでデザイン／プロトタイプの作業を続けることを目的としていますが、こちらを使うことになる場合もあります。選択肢は 2 つあり、それぞれ動作が異なります。

• *「Claude Code Web に送信」*を選ぶと、新しい claude.ai/code セッションが開き、デザイン一式がそのセッションの作業ディレクトリにすでに配置されています。保存や添付が必要なファイルはなく、最初からそこにあります。その新しいセッションで、作業ディレクトリの内容を確認して、このスキルを使うよう Claude に指示してください。
• 「ローカルのコーディングエージェントに送信」を選ぶと、ローカルのターミナルで Claude Code に貼り付けるプロンプトが表示されます。ご注意ください。執筆時点では、このデフォルトのプロンプトは「Claude Design connector」に依存していますが、ローカル版の Claude Code には同梱されておらず、ほぼ確実にエラーが表面化しないまま失敗します（詳細はanthropics/claude-code#69246を参照してください）。同じダイアログに「代わりに zip をダウンロード」**という選択肢があります。こちらは実際に機能し、デザインファイルの zip がダウンロードされます。その zip を保存し、ローカルの Claude Code に渡すか（または先にプロジェクトフォルダーに解凍し）、それに対してこのスキルを使うよう Claude に指示してください。

どちらの方法を使った場合でも、scripts/fix_export.py はファイル、zip、またはディレクトリ全体を受け付けます。unpack.py が対象の形式を判別するため、特定の形式に限定されません。特に方法 B について知っておくべき点が 1 つあります。方法 B の一式は Design 独自の *.dc.html キャンバスファイル形式で、このスキルの修復パイプラインが実際に対応・検証されている .pptx とは異なるものです（references/defect-classes.md を参照）。.dc.html の一式は、十分にテストされた経路ではなく、ベストエフォートの HTML 経路（convert_html.py）に渡されます。壊れたデッキ／PDF のエクスポートを修正したい場合は、方法 A を選んでください。

どちらの方法でも、その後 Claude は scripts/fix_export.py を実行し、修復済みの .pptx（方法 A）または PDF と、何が問題で何を変更したかを正確に説明するレポートを返します。PowerPoint／Keynote／Google Slides で編集を続けたい場合は、修復済みの .pptx を開いてください。成果物が PDF でよい場合は、.pdf をそのまま使えます。

正直に言うと、Claude 製品のボタンやフローは時間とともに変わります。また、方法 B の説明は、その引き渡しを実際に試した結果ではなく、Claude Code の公開課題トラッカーに基づいています。表示内容がここでの説明と異なっていても、そこで行き詰まらないでください。うまくいく方法で実際のデザインファイルを Claude Code に渡し、このスキルを使うよう Claude に指示してください。unpack.py は渡されたものを判別できるように作られています。

修正される内容の概要

#	不具合	症状	修正方法
1	[Content_Types].xml に、zip 内に存在しないパーツが宣言されている	一部のコンバーターで変換に失敗したり、スライドが欠落したり、出力が文字化けしたりします。PowerPoint では、気づかないうちに「修復」され、問題が見えなくなる場合があります	python-pptx で読み込んで再保存します（実際に存在する内容からマニフェストを再構築します）
2	図形のボックスがスライドの端からはみ出している	スライドを厳密なビューポートとして扱うレンダラーで、図形が切り取られることがあります	図形をスライド内に戻します（図形自体がスライドより大きい場合は、縮小してから表のグリッドを再スケーリングします）
3	カスタム Web フォント（実際に確認されたものは Inter、Plus Jakarta Sans、JetBrains Mono）が使用されているが、埋め込まれていない	そのフォントがないレンダラーでは別のフォントに置き換えられ、見た目やテキストの計測結果が変わります	変換前に、レンダラーが参照できる場所へ、対応するフォントファイルをインストールするか取得して配置します
4	LibreOffice では、文字間隔が設定された（a:rPr spc）テキストランの末尾が切り取られる	文字間隔を広げたラベル／キッカー／バッジの末尾1～4文字が欠けます。これは通常、#2 も該当する場合でも「テキストが切れている」実際の原因です	文字間隔を無効化したコピーのみを LibreOffice でレンダリングします。返される .pptx では、編集用に元の文字間隔が維持されます

実行方法

すべて1つのスクリプトで実行できます。

python3 scripts/fix_export.py <input> --out-dir <where to write results>

<input> に指定できる形式は次のとおりです。

• 直接渡す .pptx（実際に Claude Design のエクスポートで生成されているのはこの形式です。zip に格納されているとは限りません）
• .zip — 展開して、まず .pptx を検索し、次に HTML/CSS/JS バンドル（index.html + アセット）、最後に単体の .pdf を検索します
• 単体の .pdf — ソースがない場合、修復できる範囲は限られます。下記を参照してください

入力に通常とは異なる点がある場合は、実行前にスクリプト自身の docstring を読んで、パイプラインの全容を確認してください。実際のコードの動作と常に一致するよう更新されています。

実行後は <out-dir>/repair_report.md を確認してください。ここには、パッケージ構造の問題、位置変更／サイズ変更されたすべての図形（スライド番号、変更前後の座標）、デッキで使用されているすべてのフォントの状態（インストール済み／取得済み／代替フォントにフォールバック）、文字間隔の回避策が適用されたかどうか、最終 PDF の検証結果（ページ数とスライド数の比較、予期せず空白に見えるページ、ページの端に接しているテキスト）が順に記録されています。このレポートはログとして残すだけでなく、ユーザーに見せるためのものなので、ユーザーに提示してください。このスキルの目的は「何も黙って変更しないこと」です。

出力は <out-dir> に保存されます。

• *.repaired.pptx — 完全に編集可能で、構造がクリーンです。キャンバス外の図形はなく、元の文字間隔も維持されています
• *.repaired.pdf — クリーンな PDF です。文字間隔を無効化したレンダリング用コピーから変換されるため（不具合 #4 を参照）、文字間隔を広げたラベルが切り取られません
• repair_report.md / repair_report.json

ソースファイルのない単体 PDF が入力の場合

パッケージ構造、図形のジオメトリ、フォントの置換といった構造上の修復には、編集可能なソースが必要です。固定されたベクターパスとラスタライズされたテキストに平坦化済みのファイルでは、図形の移動もフォント参照の修正もできません。fix_export.py は同じ PDF 検証（ページ数の妥当性、空白ページの確認、ページ端からのはみ出しの確認）を実行するため、少なくとも PDF 自体が壊れているように見えるかどうかを正直に確認できます。ただし、修正が行われたかのように伝えず、その旨をユーザーにはっきり説明してください。実際に修正できるのはソースがある場合なので、Design から .pptx／zip として再エクスポートできるかユーザーに尋ねてください。

入力が HTML/CSS/JS バンドルの場合

この処理（scripts/convert_html.py）はベストエフォートであり、.pptx の処理とは異なり、実際の不具合調査に基づくものではありません。この形式のサンプルがなく、テストできていないためです。HTML デッキの印刷から PDF への変換でよく問題になる一般的な修正を適用します（背景や色の印刷を強制する、overflow: hidden とスクロールに依存している要素の非表示を解除する、要素の途中でのページ分割を回避する）。また、マークアップに含まれるヒントからページサイズを選びます。実際に HTML のエクスポートで問題が発生した場合は、既存の一般的な修正ですべて対処できると考えず、この処理を出発点として、references/defect-classes.md の末尾にある新しいケースの診断方法（レンダリング、比較、切り分けを行い、マークアップだけから推測しない）を読んでください。

このスキルの拡張

デッキに上記の表にない不具合がある場合は、不具合 #4 の発見に使った手法を応用できます。XML/CSS だけを見てデバッグしないでください。「構造上問題ない」と「正しくレンダリングされる」は別の主張であり、ユーザーが報告しているのは後者だけだからです。手を加えていない元ファイルを PDF にレンダリングし、特定の変更を 1 つだけ適用したコピーもレンダリングして、両者を比較してください。ジオメトリとフォントの修正だけでは目に見えるクリッピングが解消されず、その後にレタースペーシングの不具合が確認されたのも、この方法によるものでした。scripts/validate_pdf.py では、すでにページ数、空白ページ、端からのはみ出しをチェックしています。毎回の実行時に自動で確認する価値のある、ほかの簡単で客観的な指標が見つかった場合は、これに追加してください。