deckkit-ppt-replica

DeckKit PPT レプリカ

DeckKit を使って、元のスライド画像を再利用可能で、ほとんどの要素を編集できる PPTX に再構成する場合に、このスキルを使用します。

実行時の規律

このワークフローは、各ステップで監査されます。チェックポイントを省略したり、後続の領域をまとめて処理したり、ユーザーが最終的な PPTX しか確認しないと決めつけたりして、速度を優先しないでください。すべての bbox、領域のレンダリング、アイコンの並列比較、qa.md は、ユーザーが確認できるレビュー資料として扱ってください。bbox の精度、ルールの遵守、現在のステップで定められた目標の達成、意味的な比較、各ステップの出力品質に注力してください。ゲートの要件を満たしていない場合は、そこで停止して修正するか、検証上の不足を記録してから先に進んでください。

絶対遵守の監査モード

このスキルは、最善努力で PPT を生成するワークフローではなく、監査を伴う再構成ワークフローです。必要なゲートの証拠がそろう前に完全な PPTX の作成を優先した場合、その実行は失敗と見なされます。

失敗条件：

• 現在の領域のゲートを通過する前に、後続の領域用 SVG アセットを作成する。
• 現在の領域のゲートを通過する前に、後続の領域用 DeckKit 描画コードを記述、有効化、または生成する。
• それ以前のすべての領域のゲートを通過する前に、スライド全体の PPTX を生成する。
• スライド全体を実装した後で、領域の QA を作成する。
• アイコン／SVG を、対象となる領域が現在の領域になる前に、1 回のスクリプト実行ですべてまとめて作成する。
• PASS／不足事項を明確に報告し、ユーザーの確認を待つことなく領域を進める。

各領域のゲートを通過したら、停止してユーザーに確認を求めてから続行してください。沈黙や作業の勢いを、次の領域に着手する承認と解釈しないでください。常に短期的な目標は「現在のゲートを完了して停止する」であり、「スライド一式を完成させる」ではありません。

必須の参照資料

実装を始める前に、SKILL_DIR をこの SKILL.md が格納されているディレクトリとして解決し、以下を読み込んでください。

• $SKILL_DIR/reference/deckkit-capabilities.md：DeckKit API の機能、ルート名、画像ヘルパー、実装上の注意点。

initial-bbox.json の基準として、この SKILL.md に埋め込まれた bbox スキーマを使用してください。例に固有の LESSONS-LEARNED.md は必須ではありません。このスキル自体が、継続的に活用できる教訓を記録する場所です。このリポジトリ自体を保守する場合は、docs/bbox-route-aware-segmentation-proposal.md、docs/deckkit-llm-capabilities.md、または Workbench のソースファイルを補足資料として使用できますが、公開されたスキルの利用者がこれらを参照する必要はありません。

アイコンについては、以下を使用してください。

• $SKILL_DIR/reference/lucide/lucide-icons.jsonl
• $SKILL_DIR/reference/lucide/icons/<icon>.svg

これらのスキル参照資料を、現在のリポジトリ、親ディレクトリ、またはユーザーのホームディレクトリから探さないでください。インストール済みのスキルでは、参照ディレクトリが /Users/<USER>/.agents/skills/deckkit-ppt-replica/reference/ にある場合があります。そのスキル専用のディレクトリを直接使用してください。lucide アセットを探すために、find /Users/<user> ... のような広範囲を対象とするコマンドを実行してはいけません。必須のスキル参照資料が見つからない場合は、無関係なファイルで代用せず、スキルのインストールに問題があることを報告してください。

ワークフロー

1. 作業フォルダーを作成する

追跡対象のソース例と同じ場所に、追跡対象外の作業用例フォルダーを作成します。

examples/<example-name>-bbox-work/
  input/
  manifests/
  scripts/
  crops/
  preview/
    regions/
    icons/
  svg/
  output/

ソース画像は、次のような意味的に関連する追跡対象の例フォルダーに置いてください。

examples/<example-name>/source.png

フォルダーを作成する前に、pwd と、利用可能であれば git rev-parse --show-toplevel を実行して、現在の書き込み可能なリポジトリルートを確認します。任意のソース画像パスの隣ではなく、その書き込み可能なリポジトリルートの下に作業フォルダーを作成してください。意図したパスに書き込めない場合は、現在のリポジトリ内の対応するパスを選び、その選択を明記してください。

ソース画像を次の場所にコピーまたはミラーリングします。

examples/<example-name>-bbox-work/input/source.png

すべてのスクリプトで、ローカルソースとして input/source.png を読み込んでください。元のソースパスは、ノートまたはマニフェスト内の来歴情報としてのみ保持します。生成される再構築ファイルはすべて examples/<example-name>-bbox-work/ の下に置いてください。これには、npm パッケージファイル、スクリプト、マニフェスト、切り抜き画像、SVG アセット、プレビュー、QA 成果物、出力 PPTX ファイルが含まれます。生成された作業成果物をソース例のフォルダーやリポジトリルートに書き込まないでください。

2. 初期 BBox JSON を生成する

未加工の BBox レビューデータ形式で manifests/initial-bbox.json を生成します。

{
  "title": "Example bbox review",
  "imageAssetId": "source",
  "image": { "width": 1672, "height": 941 },
  "activeElementId": "canvas",
  "instructions": "Review bbox geometry and route-aware reconstruction fields.",
  "status": "needs-human",
  "elements": []
}

各要素には、id、必要に応じて parentId、label、kind、bbox、route、editability、renderRole、childrenPolicy、granularityFeedback、routeReason、reviewStatus を含めてください。

この未加工の BBox レビュー用スキーマをそのまま使用してください。列挙値を独自に追加しないでください。

interface BBoxReviewData {
  title?: string
  imageAssetId: string
  image: { width: number; height: number }
  activeElementId?: string
  instructions?: string
  status?: 'needs-human' | 'complete'
  elements: ElementNode[]
}

interface ElementNode {
  id: string
  parentId?: string
  label: string
  kind: ElementKind
  bbox: { x: number; y: number; w: number; h: number }
  description?: string
  reviewStatus?: ReviewStatus
  confidence?: number
  notes?: string
  route?: ReconstructionRoute
  editability?: Editability
  renderRole?: RenderRole
  childrenPolicy?: ChildrenPolicy
  granularityFeedback?: GranularityFeedback
  routeReason?: string
}

type ElementKind =
  | 'architecture-box'
  | 'canvas'
  | 'card'
  | 'content-row'
  | 'decorative-background'
  | 'decorative-line'
  | 'decorative-shape'
  | 'footer'
  | 'icon'
  | 'section'
  | 'section-body'
  | 'section-header'
  | 'text'
  | 'text-group'
  | 'group'
  | 'image'
  | 'shape'

type ReviewStatus = 'pending' | 'reviewing' | 'accepted' | 'needs-agent'

type ReconstructionRoute =
  | 'layout-only'
  | 'native-shape'
  | 'native-text'
  | 'svg-image'
  | 'editable-vector'
  | 'imagegen'
  | 'source-raster'
  | 'drawio-svg'

type Editability = 'none' | 'asset' | 'group' | 'element'
type RenderRole = 'render' | 'layout' | 'context'
type ChildrenPolicy = 'none' | 'optional' | 'required'
type GranularityFeedback = 'ok' | 'too-coarse' | 'too-fine'

スキーマのルール：

• レビューがすでに完了している場合を除き、初期レビュー JSON では status: "needs-human" を使用します。
• 初回確認の要素には reviewStatus: "pending" を使用します。
• 部分的なスニペットではなく、完全な JSON ファイルを作成してください。列挙文字列値を行の途中で改行しないでください。"architecture-\nbox" のような値は無効です。
• 安定した一意の id 値を使用し、すべての parentId が既存の要素を参照するようにしてください。
• kind: "line" は出力しないでください。表示される線、区切り線、矢印、コネクター、セパレーターには kind: "decorative-line" を使用してください。
• arrow、rect、rounded-rect、title、body、architecture-card のような kind 値を独自に追加しないでください。
• 見た目の実装意図は、未対応の kind 値ではなく route に記述してください。たとえば、コネクターには通常、kind: "decorative-line" と route: "native-shape" または route: "editable-vector" を使用します。
• JSON を引き渡す前に、解析し、kind、route、editability、renderRole、childrenPolicy、granularityFeedback、reviewStatus、トップレベルの status が上記の列挙値に一致することを検証してください。

ルートの意味：

• layout-only：グループ化、配置、コンテキストのみを表します。直接描画してはいけません。
• native-shape：PowerPoint のプリミティブ図形、線、矢印、カード、帯、コンテナーです。
• native-text：編集可能な PowerPoint テキストボックスです。
• svg-image：画像として挿入される受け入れ済み SVG です。ベクターとして拡大縮小できますが、パスは編集できません。
• editable-vector：PowerPoint の図形、または作成した SVG／プリミティブのグループとして編集可能にする、意味を持ったベクタービジュアルです。
• imagegen：生成されたラスターアセットです。
• source-raster：ソース画像の切り抜き、またはユーザー提供のビットマップです。
• drawio-svg：SVG にエクスポートして埋め込む、構造化された図です。

粒度のルール：

• 「実装時に、ここにはちょうど1つの要素が配置されますか？」と確認します。
• はいの場合、レンダリング用のバウンディングボックスは1つで十分です。
• いいえの場合、実装時に配置される要素ごとに正確に分割します。
• 親ボックスに指定できるのは renderRole: "layout" または renderRole: "context" のみです。
• 同じ可視オブジェクトに対して重複するレンダリング用ボックスを作成しないでください。たとえば、セクションのラッパーは layout-only、本文カードは native-shape のレンダリング要素にできます。
• セクション、カード、行の親が子と同じ可視オブジェクトを表す場合、renderRole: "render" にできるのはどちらか一方だけです。親の構造には通常、renderRole: "layout" または renderRole: "context" とともに route: "layout-only" を指定します。
• 必要な子ボックスが見えていて推測できる場合、初回の回答で、そうと分かっていながら granularityFeedback: "too-coarse" を出力しないでください。その時点で分割します。
• 編集可能なアイコン行では、アイコンとラベルごとに子ボックスを作成するか、アイコンとラベルのペアごとにボックスを作成し、その下にアイコンとテキストの子ボックスを追加します。編集可能な再構成を意図している場合、6つのアイコンを1つのレンダリング用バウンディングボックスにまとめないでください。
• 装飾的な不規則な縁取り、飾り板、リボン、タブ、バッジ、または編集可能なテキストを囲む基本的でないフレーム装飾があるコンテナでは、ビジュアルフレームとテキストを分けます。フレームには通常、route: "svg-image" または route: "editable-vector" を指定した kind: "decorative-shape" のレンダリング要素を1つ割り当てます。その中の読み取り可能なテキストは、別の route: "native-text" レンダリング要素にします。テキストを意図的に編集不可能なアートワークにする場合を除き、SVGフレームにテキストを含めないでください。

SVGルートの適格性：

• svg-image または editable-vector のレンダリングノードは、アイコン、ロゴ、ピクトグラム、装飾フレーム、コネクター群、図の断片など、実装時に単一の作成済みアセットとして配置する、分割できないベクター風のビジュアルアセットを表す必要があります。
• 枠線、テキスト、イラスト／アイコンを含むという理由だけで、UI、カード、モジュール全体を1つの svg-image にしないでください。読み取り可能なテキスト、枠線／背景、ビジュアルアセットを含むカードは複合レイアウトであり、単一のSVGアセットではありません。
• 複合カードでは、親に route: "layout-only" と renderRole: "layout" または renderRole: "context" を指定した kind: "card" または kind: "group" を作成します。そのうえで、可視の子要素を分割します。枠線／背景は native-shape、各テキストブロックは native-text、実際の各アイコン／イラストは適切なルートを指定した独立した icon／image／decorative-shape ノードにします。
• カード内のSVGに適したビジュアルが小さい場合は、そのビジュアルの内側にぴったり合うようにバウンディングボックスを設定します。カードの装飾、ラベル、キャプション、バッジ、周囲の余白までSVGのバウンディングボックスに含めないでください。
• 編集可能／読み取り可能なテキストと無関係なレイアウト装飾が候補のSVGバウンディングボックスに含まれる場合、範囲が広すぎるため、初回のJSONを出力する前に分割してください。

3. 必須チェックポイント：Workbenchでの任意レビュー

manifests/initial-bbox.json の作成と検証が終わったら、そこで停止してください。まだ依存関係のインストール、再構成用スクリプトの作成、SVGの作成、スライドの生成は行わないでください。

より正確な initial-bbox.final.json を生成するために、Workbenchを任意で利用できることをユーザーに伝えてください。メリットとデメリットを明確に説明してください。Workbenchでは再構成前にバウンディングボックスの形状、階層、ルート、粒度を修正できます。これにより、通常は後工程での見た目の修正回数とトークン使用量を減らせます。Workbenchを利用しない場合は initial-bbox.json から再構成を続けられますが、バウンディングボックスの誤りを手作業で修正していないため、後工程の領域QAでAIによる視覚調整がより多く必要になる場合があります。

次の手順を正確に案内してください。

https://artifact-kit.github.io/artifact-kit/

1. URLを開きます。
2. 元画像をアップロードします。
3. manifests/initial-bbox.json をアップロードします。
4. 必要に応じてボックス／ルートを調整します。
5. <input-file>.final.json をダウンロードします。
6. ダウンロードしたファイルを manifests/ に initial-bbox.final.json として配置するか、作業を続けるためにファイルのパス／内容を返信します。

ユーザーが initial-bbox.final.json を提供するか、Workbenchをスキップして initial-bbox.json で進めると明示するまで、作業を続けないでください。どちらのパスが選択されたか記録してください。このチェックポイントを黙ってスキップしないでください。

4. DeckKit の再構成を設定する

現在の xxx-work フォルダー内で再構成を設定します。packages/deckkit のようなリポジトリ内のパッケージソースフォルダーに依存しないでください。公開済みのスキルを使うユーザーは、そうしたファイルを持っていないためです。

この手順の完了後に推奨される作業フォルダーの構成：

examples/<example-name>-bbox-work/
  package.json
  node_modules/
  input/
    source.png
  manifests/
    initial-bbox.json
    initial-bbox.final.json
  scripts/
    crop-assets.mjs
    build-svg-assets.mjs
    generate.mjs
  crops/
  preview/
    regions/
    icons/
  svg/
  output/

xxx-work フォルダー内に package.json を作成または更新します。

{
  "type": "module",
  "scripts": {
    "crop": "node scripts/crop-assets.mjs",
    "svg": "node scripts/build-svg-assets.mjs",
    "generate": "node scripts/generate.mjs"
  },
  "dependencies": {
    "@artifact-kit/deckkit": "latest",
    "@artifact-kit/deckkit-pro": "latest"
  }
}

同じ作業フォルダー内で、npm から依存関係をインストールします。

npm install

npm でインストールしたパッケージからインポートします。画像処理には、sharp に直接依存せず、DeckKit Pro のエクスポートを使用します。

import DeckKit from '@artifact-kit/deckkit'
import deckkitPro, {
  compareImages,
  cropImage,
  getImageInfo,
  overlayImages,
  resizeImage,
  sampleColor,
  writeSvgToPng,
  writeImage,
} from '@artifact-kit/deckkit-pro'

const pptx = new DeckKit()
pptx.use(deckkitPro())
pptx.defineLayout({ name: 'SOURCE', width: 13.333, height: 7.5 })
pptx.layout = 'SOURCE'
pptx.theme = {
  headFontFace: 'Microsoft YaHei',
  bodyFontFace: 'Microsoft YaHei',
  lang: 'zh-CN',
}

生成するすべてのアセットと出力を、同じ xxx-work フォルダー内に保存します。

• 元画像のコピー：input/source.png
• クロップ：crops/
• 作成した SVG：svg/
• ビジュアルプレビューと QA アーティファクト：preview/
• 生成した PPTX：output/
  • *-preview.pptx：挿入前に SVG アセットを PNG にラスタライズする、ビジュアル確認用ビルドです。
  • *-deliverable.pptx：SVG アセットを直接挿入する、最終納品用ビルドです。

すべてのビットマップ準備には、DeckKit Pro の画像ヘルパーを使用します。

const cropped = await cropImage(sourcePath, { x, y, width: w, height: h })
await writeImage(cropped, 'crops/asset.png')

クロップの抽出とデッキの生成は分けてください。

• scripts/crop-assets.mjs：最終版の bbox JSON を読み込み、すべての source-raster レンダリングアセットを cropImage でクロップして crops/ に保存し、manifests/crop-assets.json のようなクロップマニフェストを書き出します。
• scripts/build-svg-assets.mjs：領域 ID を受け取り、その領域の SVG アセットだけを作成して、最終版の .svg ファイルを svg/ に保存します。SVG のソースコードは generate.mjs に含めないでください。領域内では SVG／アイコンを 1 つずつ作成し、QA を実施します。
• scripts/generate.mjs：領域／ステージ ID を受け取り、最終版の bbox JSON、クロップマニフェスト、既存の SVG ファイルを読み込み、完了済みの領域と現在の領域だけを対象に PPTX を生成します。アセットマニフェストが見つからない、または古くなっている場合を除き、元画像を再クロップしたり、SVG のソースコードを作成したりしないでください。デフォルトでは、指定されたステージのプレビュー用ビルドと納品用ビルドの両方を生成します。

スクリプトの契約：

• build-svg-assets.mjs は、明示的に指定した現在の領域 ID を 1 つ必須とします。all をサポートしたり、デフォルトで all にしたり、将来の領域の SVG を生成したりしてはいけません。
• generate.mjs は、明示的に指定した現在の領域／ステージ ID を 1 つ必須とします。すべての領域に PASS の qa.md があるか、検証上のギャップが明示的に記録されるまでは、all、full、最終的な全スライド生成をサポートしてはいけません。
• 最終的な全スライドビルドが必要な場合、スクリプトはまず、必要なすべての preview/regions/<region-id>/qa.md が存在し、PASS であるか、明示的なギャップが記録されていることを確認する必要があります。
• ステージの順序は、信頼ではなく QA ファイルによって強制する必要があります。後続の領域をレンダリングできるのは、前のすべての領域ゲートに証拠がある場合に限られます。

bbox JSON は、位置指定とレビューの証拠であり、実行時のレンダリング DSL ではありません。generate.mjs を、bbox の要素をループし、fontSize(element)、textColor(element)、shapeStyle(element)、id.includes(...) のような汎用ヘルパーを使い分ける、汎用的な route／kind／id 駆動のレンダラーとして実装しないでください。このような失敗パターンでは、従来型の if／else コードにビジュアル上の判断が隠され、LLM 駆動の再構成の目的が損なわれます。

必須のアプローチ：

• bbox は座標、サイズ、元画像のクロップを取得するためだけに使用します。
• LLM に、現在の領域向けの明示的な DeckKit コマンドを、意味を持つオブジェクトごとに記述させます。
• テキストの内容、フォントサイズ、色、ウェイト、塗りつぶし、線、レイヤー順、アイコンファイル、クロップファイルなど、ビジュアル上の判断を呼び出し箇所で明示します。
• ヘルパーは、座標変換、ファイル検索、および元画像と照らし合わせてビジュアル仕様が検証済みの、真に繰り返し使われるコンポーネントに限定します。

悪いパターン：

for (const element of elements) {
  if (element.renderRole !== 'render') continue
  if (element.route === 'native-text') addText(slide, element)
  else if (element.route === 'native-shape') addShape(slide, element)
  else if (element.route === 'svg-image') addImage(slide, element)
}

function textColor(element) {
  if (element.id.includes('core')) return RED
  if (element.id.startsWith('sensing')) return BLUE
  return DARK_BLUE
}

良いパターン：

function box(id) {
  return pbox(getElement(id).bbox)
}

async function drawProjectBackground(slide) {
  slide.addShape('roundRect', {
    ...box('project_background_card'),
    fill: { color: 'FFFFFF' },
    line: { color: 'B7CAF4', width: 0.8 },
  })
  slide.addImage({ path: 'svg/project_background_header.svg', ...box('project_background_header') })
  slide.addText('项目背景', {
    ...box('project_background_header_text'),
    fontSize: 15.5,
    bold: true,
    color: 'FFFFFF',
    margin: 0,
  })
  slide.addShape('ellipse', {
    ...box('project_background_row_1_icon_circle'),
    fill: { color: 'EEF5FF' },
    line: { color: 'D4DFF4', width: 0.8 },
  })
  slide.addImage({ path: 'svg/project_background_row_1_icon.svg', ...box('project_background_row_1_icon') })
}

スライド全体をデータインタープリターとして記述してから、グローバルなスタイルルールを調整しないでください。再構成コードは、再構成対象の領域を意味に沿って記述したものにしてください。

将来の領域の SVG をまとめて作成しないでください。簡単なアセット一覧を用意するのは問題ありませんが、SVG の作成とビジュアル QA は、その領域が現在の再構成対象になったときに行います。 アセットファイルの拡張子は、ファイルの実際の形式と一致させてください。.svgファイルにはSVG XMLを含め、.pngファイルにはwriteSvgToPng、writeImage、またはその他のDeckKit Pro画像ヘルパーで生成した、本物のPNGバイト列を含める必要があります。Quick Lookや後続のプレビュー用ツールがファイルを誤認するおそれがあるため、SVGのテキストを.pngのパスに書き込まないでください。

作成したSVGアセットは、PPTXに直接挿入してください。

slide.addImage({ path: 'svg/project_background_row_1_icon.svg', x, y, w, h })

最終版のPPTXでは、SVGアセットをPNGに変換しないでください。SVGを挿入すると、アセットのベクター拡大縮小が可能な状態で保持されます。writeSvgToPngは、補助的なプレビュー／デバッグ用画像に限り使用できます。ルートがsvg-imageまたはeditable-vectorの場合、挿入するPPTアセットには使用しないでください。

SVGを多用するステージでは、次の2種類を出力する方法を使用してください。

• previewモード：DeckKit ProのwriteSvgToPngでSVGアセットをPNGに変換して挿入し、このPPTXはQuick Lookなどでの視覚的な確認にのみ使用します。
• deliverableモード：slide.addImage({ path: svgPath, ... })でSVGファイルを直接挿入します。ベクター拡大縮小が可能な状態を維持するため、引き渡しにはこちらのバージョンを使用します。
• デフォルトの生成では、視覚確認用ビルドと納品用ビルドで差異が生じないよう、同じレイアウトコードから両方のファイルを出力してください。

npm run generate -- project-background
# writes output/...-project-background-preview.pptx
# writes output/...-project-background-deliverable.pptx

デバッグでは、単一モードでの生成も可能です。

npm run generate -- project-background preview
npm run generate -- project-background deliverable

ユーザーがDeckKit Pro以外で低レベルの画像処理を明示的に求めない限り、生成する作業フォルダーにsharpを直接依存関係として追加しないでください。

ソースの寸法に基づいて、ピクセルからインチへの変換を行ってください。

function pbox(x, y, w, h) {
  return {
    x: (x / SOURCE_W) * SLIDE_W,
    y: (y / SOURCE_H) * SLIDE_H,
    w: (w / SOURCE_W) * SLIDE_W,
    h: (h / SOURCE_H) * SLIDE_H,
  }
}

wまたはhが負の値になる図形や線は、絶対に作成しないでください。

5. 読み順に沿って再構築する

大まかな領域から細部へと進めるのではなく、読み順に沿って再構築します。上から下、左から右へと作業します。まだ再構築していない領域は、あちこちに大まかなプレースホルダーを置くのではなく、空白のままにします。

理由：

• 未完成の領域を空白にした部分的なスライドなら、新しく完成させた領域の視覚的な違いがわかりやすくなります。
• スライド全体を大まかに作成すると、すべてが一度に概略的な状態になるため、領域ごとの位置合わせ、タイポグラフィ、アイコンの誤りが見えにくくなります。
• 各イテレーションでは、次の領域に進む前に、新たに完成させた領域をソースの切り抜きと照合して検証します。

実装も同じ順序で進める必要があります。まず、ヘッダーだけをレンダリングするコードから始めます。ヘッダーの QA に合格したら、次の領域のコードを追加または有効化し、同じ手順を繰り返します。スライド全体の実装を先に書き上げ、完成後のスライド全体のレンダリングを主なレビュー対象にしてはいけません。スライド全体のプレビューは、現在の領域のゲートに合格した後に限り使用できます。

密度の高い単一スライドのインフォグラフィックでは、次の領域順を推奨します。

1. ヘッダーのタイトル／サブタイトル領域。
2. 左上のセクション。
3. 上部中央／右上のセクション。
4. 左下のセクション。
5. 右下のセクション。
6. フッター。

各段階では、完成済みの領域と現在の領域だけをレンダリングします。位置合わせのガイドとして必要な場合を除き、将来の領域を大まかなプレースホルダーとして追加しないでください。ガイドとして使う場合は、出力に含めない一時的なガイドであることを明示してください。

レビュー済みの bbox JSON をもとに、セクションやカードグループなど、次に作業する範囲を定めた領域を選びます。

領域ごとの必須ゲート：

• 現在作業する領域は、厳密に1つにします。
• 変更が許可されるのは、その領域で使う SVG アセット、完成済み領域と現在の領域の DeckKit 描画コード、その領域とそのアイコンの QA ファイルに限られます。
• 現在の領域に合格する前に、将来の領域の SVG アセット、将来の領域の描画コード、スライド全体の出力、all ステージの生成、完成済みのスライド全体の実装から事後的に生成した QA を作成してはいけません。

その領域について、次の作業を行います。

1. native-text は DeckKit のテキストボックスとして配置します。
2. native-shape は DeckKit の図形、線、矢印、グラデーション、シンプルなコンテナとして配置します。
3. source-raster の切り抜きは、ビットマップが最終アセットとして意図されている場合に限り配置します。
4. その領域で必要な SVG アセットだけを作成し、レンダリングして QA を行います。
5. 承認された svg-image アセットは slide.addImage({ path: svgPath, x, y, w, h }) で配置します。
6. スライドのプレビューをレンダリングし、ソースとレンダリングから完成済み領域を切り抜いて、左右に並べた QA 画像を生成し、確認します。次の領域に進む前に比較してください。

完成した領域ごとに、次の QA ファイルを作成します。

preview/regions/<region-id>/source.png
preview/regions/<region-id>/render.png
preview/regions/<region-id>/side-by-side.png
preview/regions/<region-id>/qa.md

side-by-side.png を主要な意味比較に使います。左側にソース、右側にレンダリングを配置し、必要に応じて余白を十分に取り、白または透明の要素が見えるよう、中間色、チェッカー柄、または暗色の背景を使用します。overlay.png は任意で、形状の確認に役立つ場合にのみ使用します。意味を左右に並べて確認するレビューの代わりにはなりません。

領域の QA ファイルを作成したら、render.png と side-by-side.png を開いて目視で確認します。qa.md に PASS または具体的な問題と修正内容を記載します。その領域の QA 作業中に、テキストのはみ出し、折り返し、アイコンの大きさ、要素の欠落、意味の不一致を修正します。明らかな領域の問題を、スライド全体の最終プレビューまで先送りしてはいけません。

これは必須のゲートです。現在の領域の QA ファイルが揃い、目視で確認され、問題が修正済みまたは明示的に検証上の不足として記録されるまで、次の領域に着手してはいけません。

現在の領域のゲートが完了したら、PASS／不足事項を報告して停止します。ユーザーが次の領域への続行を承認するまで待ってください。次の領域が明らかな場合でも、自動的に作業を続けてはいけません。

6. アイコンの再構築

すべてのアイコンについて、次の作業を行います。

1. 周囲のテキストと視覚的な形状から、アイコンが表す意味を特定します。

2. grep または jq を使って、スキル内の lucide メタデータを検索します。例：

   grep -Ei "thermometer|temperature|wifi|cloud|database" "$SKILL_DIR/reference/lucide/lucide-icons.jsonl"
   

3. 最も関連性の高い SVG ソースを読みます。

   $SKILL_DIR/reference/lucide/icons/<name>.svg
   

4. 新しいアイコンを描く前に、該当する参照 SVG のソースコードを必ず読んでください。参照をそのままコピーするのではなく、輪郭、内部のシンボル、コネクター、葉脈、ゲージの弧、ベルの本体、ノードグラフなど、どの具体的なプリミティブが意味を伝えているかを理解するために使ってください。

5. アイコンを意味に沿って再構成してください。ピクセル単位で同一である必要はありませんが、同じ概念が伝わり、スライドの線幅、色、サイズ、ビジュアルスタイルに合っている必要があります。

6. アイコンが意味的な組み合わせで構成されている場合は、すべてのパスを無理に1つの連結した形にするのではなく、1つの SVG 内で複数のサブアイコンまたはサブグループとして描画してください。たとえば、「低電力センシング」アイコンは、次のようにバッテリーと稲妻のサブグループに、別の位置に配置した葉のサブグループを組み合わせることができます。

   <svg viewBox="0 0 48 72" ...>
     <g id="battery-lightning">...</g>
     <g id="leaf" transform="translate(...) scale(...)">...</g>
   </svg>
   

   サブグループは、それぞれ独立して配置できる意味単位として扱ってください。これにより、拡大縮小後に意図しない形状が合体して、台座、鎖、尾などに見えてしまうのを防げます。

7. 再構成した SVG を、対象の bbox サイズで DeckKit Pro の writeSvgToPng を使って PNG にレンダリングし、採用前にアイコンそのものを目視で確認してください。スライド全体のプレビューだけに頼らないでください。小さなアイコンの問題は、スライド全体の縮尺では見えなくなることがあります。

8. 元のアイコンを切り抜き、レンダリングしたアイコンと比較してください。意味の一致、線の太さ、プロポーション、透明度の扱い、サブグループの配置に問題があれば調整してください。

新しく作成した SVG のローカルでのアイコン目視確認を省略してはいけません。

現在の領域について、SVG ファイルは1つずつ作成してください。directIconRefs[id] ?? ...、id.startsWith('sensing') ? BLUE : ...、id.includes('header_icon') ? WHITE : ... のように、オブジェクトマップとデフォルトのスタイル分岐を使って、スライド全体の SVG ライブラリを一括生成してはいけません。問題はファイル書き出しにスクリプトを使うことではありません。異なるビジュアルグループを同じデフォルトのスタイル規則に当てはめることが問題です。

ビジュアルグループへの所属は、アイコン仕様の一部として扱ってください。同じ意味のアイコンでも、領域によって別々の SVG コードやパラメーターが必要になる場合があります。

• 淡い円の中にある、プロジェクトの背景を表す大きな温度・湿度アイコンは、小さなセンシングレイヤーの温度センサーアイコンとは異なるビジュアルアセットです。
• 同じシステムアーキテクチャのセンシンググループ内のアイコンでも、青いセンサーアイコンの中に緑色の空気質・葉アイコンがあるなど、個別の例外がある場合があります。
• ヘッダーアイコン、フッターアイコン、サービスアイコン、シナリオアイコン、コアイノベーションアイコンには、それぞれ独自の色、サイズ、線幅、背景コンテキストがあります。

意味が似ているという理由だけで、アイコンファイル、色の規則、サイズの規則、線幅の規則、または変換を使い回してはいけません。再利用が許されるのは、元画像の切り抜きを比較し、ビジュアルグループの仕様が一致することを確認した場合のみです。一致しない場合は、別々の SVG ファイルと QA 記録を作成してください。

各アイコンの reference.txt と qa.md は、目視確認の後に作成してください。qa.md は、次の点を明示的に確認するか、修正内容を記録する必要があります。

• 元のアイコンとの意味の一致
• アイコンが実際に配置される背景コンテキストでの色とコントラスト
• 線幅と塗りつぶしの動作
• サイズ、余白、bbox 内の占有率
• 方向・向き
• 組み合わせたアイコンのサブグループ配置
• 同じビジュアルグループ内の隣接アイコンとの一貫性

作成するすべてのアイコンについて、QA ファイルを作成してください。

preview/icons/<icon-id>/source.png
preview/icons/<icon-id>/render.png
preview/icons/<icon-id>/side-by-side.png
preview/icons/<icon-id>/reference.txt
preview/icons/<icon-id>/qa.md

reference.txt には、アイコンを描く前に読んだ lucide SVG のファイルパスと、適用に際して参考にした意味上のメモを記載してください。適切な lucide の参照が見つからない場合は、試した検索と、描画前に選んだ代替案を記録してください。

side-by-side.png では、アイコンが見やすい背景上に元画像とレンダリング結果を並べてください。白または透明のアイコンには、暗い背景、チェッカー柄の背景、または元のコンテキストの背景を使用してください。白いアイコンを白い背景上で確認してはいけません。ファイルを作成したら、side-by-side.png を開いて目視で確認し、そのうえで PASS または具体的な問題・修正内容を記した qa.md を作成してください。該当領域のすべてのアイコンについて目視確認が完了するまで、次のアイコンに進んだり、その領域を承認したりしてはいけません。 透明 PNG のプレビューが Quick Look または領域 QA で黒や不正な背景として表示される場合は、プレビューのエクスポートパイプラインを直ちに修正してください。成果物では SVG を直接挿入してもかまいませんが、プレビュー PNG は QA で視覚的に信頼できるものでなければなりません。

7. 基本図形以外の装飾

曲線状のセクションヘッダー、スウッシュ、リボン、非対称タブ、カスタムのフレーム装飾など、単純な PPT プリミティブではない装飾については、次の手順に従います。

1. セマンティックな役割（ヘッダータブ、セクション境界、動きのあるスウッシュ、ブランドアクセント、区切り、背景スキン）を視覚的に特定します。
2. SVG、DeckKit プリミティブ、またはカスタムジオメトリを使って、セマンティックなレベルで再構築します。
3. レンダリング結果を元画像の切り抜きと比較します。
4. 同じレイアウト上の役割と視覚的なリズムが再現されるまで調整します。

境界、階層、繰り返しのスタイル、または読み順を定めるものでない限り、画像生成で偶然生じたアーティファクトは再現しないでください。

明らかなグラデーションの帯、バー、リボン、ヘッダー／フッターのストリップには、まず DeckKit／DeckKit Pro のグラデーション機能を使用してください。正確な API が不明な場合は、無地のブロックに切り替える前に、インストール済みのパッケージ／型定義を調べるか、作業フォルダーで最小限の実験を行ってください。単色による近似が許可されるのは、グラデーションの試行に失敗したことと、視覚的な影響が検証ギャップとして記録されている場合に限ります。

8. ビットマップが必要なアセット

SVG／プリミティブでは現実的に再構築できないアセットについては、次の手順に従います。

1. まず、目的のアセットを元画像からきれいに切り抜けるか判断します。可能な場合は、元画像から切り抜いて使用します。
2. きれいに切り抜けない場合は、Seedream／image-to-image プロンプトを作成します。
3. プロンプトでは、目的のオブジェクト／領域のみを出力し、無関係な領域はすべて空白または透明／白にするようモデルに指示します。どちらにするかは、意図する切り抜きに応じて決めます。
4. セマンティックな内容と遠近感を保ち、無関係な再デザインを求めないでください。

アセットを再生成できるよう、プロンプトは作業フォルダーに保存します。

9. 検証

各領域の作業後に、次の項目を確認します。

• 現在の作業段階の PPTX をプレビュー画像にレンダリングします。
• 各 preview/regions/<region-id>/qa.md に PASS が記載されているか、明示的なギャップが記録されていることを確認します。
• 各 preview/icons/<icon-id>/qa.md に PASS が記載されているか、明示的なギャップが記録されていることを確認します。
• 現在の領域／アイコン QA 画像を直接確認します。全スライドのレンダリングで代用しないでください。
• 予定どおりにテキストが編集可能であることを確認します。
• テキストが領域からあふれている、ラベルが切れている、意図しない折り返しが発生している領域がないことを確認します。
• レイアウト専用のボックスが PPT オブジェクトを生成していないことを確認します。

最後に、次の項目を確認します。

• すべての領域ゲートを通過してから全スライドを比較します。領域／アイコン QA の代わりに全スライドを使用しないでください。
• プレビュー用および納品用の PPTX ファイルを、unzip -t または利用可能なパッケージ整合性チェックで検証します。
• SVG を多用する成果物については、最終 PPTX にラスタライズされた PNG の代替物だけでなく、SVG アセットが直接含まれていることを確認します。
• PowerPoint が修復を求めることなく開くことを確認します。

最終回答では、完了した出力と検証ギャップを明確に分けてください。Workbench の最終 JSON、領域ごとの QA、アイコンごとの QA、PowerPoint のオープンチェック、またはその他の必須検証を省略した場合は、すべて完了したかのように示さず、省略したことを明記してください。

再構築中に再利用可能な DeckKit の機能または制限が判明した場合は、このスキルに同梱されている reference/deckkit-capabilities.md を更新してください。artifact-kit リポジトリ自体を保守する場合は、そのローカルドキュメントが他のツールに読み込まれるソースであれば、docs/deckkit-llm-capabilities.md も更新してください。