app-icon-gen

アプリアイコン生成

JSON 仕様から、再利用可能なクロスプラットフォームのアイコンソースアセットを作成します。通常の手順は、意味のあるレイヤーを使った作成です。少数の意味のある SVG／基本形状レイヤー、または意図的にシンプルにした PNG のフォールバックレイヤー、角丸のプレビューアセット、角丸にしないアプリアイコン／ソースアセット、検証用の証拠を用意します。Apple Icon Composer のパッケージ化は任意のアダプターであり、デフォルトの要件ではありません。

このスキルでは、macOS 上で Icon Composer に同梱された ictool がローカルで利用できる場合、レンダリング済み PNG を書き出せます。ただし、書き出された PNG ファイルを超えて、アプリへの統合や最終的なプラットフォームでのレンダリングを証明するものではありません。

必須要件

新規作成または修復するアイコンごとに、生成ルートは 1 つだけ使用します。ユーザー向けの納品ディレクトリがそのルートです。

• target_platforms は任意のメタデータです。推測による補完、対象の追加、または Apple 以外のプラットフォームの却下をせず、ユーザーが指定したプラットフォーム名をそのまま受け入れます。
• まず、再利用可能な SVG／PNG ソースアセットを必ず納品します。内容を確認した後、ネイティブプラットフォーム向けの書き出しを希望するかユーザーに尋ねます。専用アダプターなしに、ネイティブの Android、Windows、Web、tvOS、visionOS 向けパッケージを納品したと主張してはいけません。
• Apple 向けのパッケージ化をリクエストするには、Apple のターゲット（iOS、iPadOS、macOS、watchOS）または Apple の deliverable_type を指定する必要があります。その場合に限り、.icon バンドルと、任意で apple/ レンダリングを作成します。
• Apple アダプターを通じて watchOS がリクエストされた場合は、円形クロップと 1088px の Default レンダリングを個別に確認します。
• 生成の前に、現在の仕様を <delivery>/tmp/work/spec.json に書き込みます。
• ユーザーのソース画像／ベクター、または選択済みの生成コンセプトがある場合、表示するソース証拠ファイルは <delivery>/<delivery-name>.origin.png または <delivery>/<delivery-name>.origin.svg のいずれか 1 つだけにします。選択されていない候補は <delivery>/tmp/work/ に置きます。
• 中間生成物はすべて、作成時点で <delivery>/tmp/work/ に置きます。マスク、しきい値テスト、抽出した前景、トレース候補、比較画像、メモ、修復用の作業ファイルが含まれます。
• <delivery>/tmp/work/spec.json を指定して、author-icon --spec <delivery>/tmp/work/spec.json --out <delivery> を実行します。
• 再実行時は、生成されたルートファイル、layers/、.icon/、apple/、tmp/reports/ を上書きできます。ただし、現在の仕様で tmp/work/spec.json を置き換える場合を除き、既存の tmp/work/ は保持し、選択されたソースが変更されない限り .origin.png／.origin.svg も保持する必要があります。
• 別のディレクトリにパッケージ全体を生成し、それを納品ディレクトリに再配置したりコピーしたりしてはいけません。
• 生成された layers/、.icon/Assets、または icon.json を直接編集してはいけません。仕様を更新して再生成します。

通常の納品ディレクトリ構成：

<delivery>/
  <delivery-name>.preview.svg
  <delivery-name>.preview.png
  <delivery-name>.svg
  <delivery-name>.png
  <delivery-name>.origin.png or <delivery-name>.origin.svg  # when source evidence exists
  <Name>.icon/                        # optional Apple adapter
  apple/                              # optional Apple renders
    iOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    macOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    watchOS/Default.png
  layers/
  tmp/
    reports/
    work/
      spec.json

表示される納品ルートには、.svg、.png、.preview.svg、.preview.png、.origin.png、.origin.svg、.icon、apple/、layers/、tmp/ のみを置きます。

ワークフロー

1. 質問する前に、提供されたソースを確認します。添付ファイル、パス、アプリのメタデータ、既存のアセット、スクリーンショット、SVG／ロゴファイル、.icon バンドル、プロジェクト内のソースベクターを確認してください。
2. ソース変換、コンセプト生成、セマンティックな直接作成、既存パッケージの調整から、いずれか1つの方法を選びます。対象プラットフォームが判明している場合に限り、記録します。
3. 以下の、選択した方法に該当するリファレンスのみを読みます。
4. <delivery>/tmp/work/spec.json を作成または更新し、レイヤーは下から上への視覚的な順序で並べます。ソースの根拠がある場合は、選択したソースまたはコンセプトを <delivery>/<delivery-name>.origin.png または <delivery>/<delivery-name>.origin.svg にコピーします。
5. 出力先ディレクトリに直接生成します。汎用 SVG／PNG アセットは常に書き出されます。Apple アダプターが要求され、Icon Composer.app の ictool が利用可能な場合は、apple/ に Apple 用レンダリングも書き出されます。
6. verify を実行します。参照画像がある場合は --reference を追加します。参照画像のキャンバス、サイズ、またはマスクがプレビューのキャンバスと異なる場合に限り、事前に参照画像を正規化します。
7. 生成されたプレビュー／アプリアセットを原寸と64pxで確認し、該当する検証証拠も確認します。Apple アダプターがある場合は、.icon/Assets、icon.json、要求された Apple 用レンダリングも確認します。人による判断が必要な場合は visual-review.json を記録します。任意のプラットフォーム向けエクスポートがないことを、一般的な失敗として扱わないでください。
8. 検証または確認に失敗した場合は、仕様を修正して再生成し、再度検証します。

スキルディレクトリからコマンドを実行するか、scripts/ に対して絶対パスの --prefix を使用します。Node のパッケージメタデータは scripts/package.json にあります。スキルのルートで npm install を実行しないでください。

npm --prefix scripts ci

delivery="/absolute/path/to/my-icon"
mkdir -p "$delivery/tmp/work"

npm --prefix scripts run author-icon -- \
  --spec "$delivery/tmp/work/spec.json" \
  --out "$delivery"

npm --prefix scripts run verify -- --out "$delivery"

参照画像がある場合：

npm --prefix scripts run verify -- \
  --out "$delivery" \
  --reference "/absolute/path/to/reference.png"

スクリプトの入力と出力には絶対パスを使用してください。

author-icon は、自身が所有していない空でないディレクトリを置き換えません。以前のスタイルレポートにある検証済みの generated_files 所有権マニフェストに記載された末端ファイルのみを更新します。そのマニフェストが、安全なレポートから導かれるファイル一覧と一致しない場合は、安全側に倒して処理を中止します。生成されたディレクトリは空になった後にのみ削除し、layers/、.icon/、apple/ 内にある場合でも、それ以外のファイルは保持します。このワークフロー外で、所有していないディレクトリをクリーンアップする場合は、必ず自分で内容を確認してから行ってください。

検証エビデンスの優先順位

サイドバイサイド表示と平均デルタだけを根拠に、修正したり別のルートに切り替えたりしないでください。失敗の種類に応じてエビデンスを選び、仕様を変更する前に確認してください。

• アイコン全体の類似性：まず reference-side-by-side.png を確認し、全体のスタイル、スケール、ボリューム、明らかなずれを調べます。
• ジオメトリ、配置、比率、レイヤーの位置合わせ：前景がずれている、小さすぎる／大きすぎる、または形状が違うと判断する前に、reference-overlay.png を確認します。
• 色、背景、グロー、シャドウ、アンチエイリアス、素材感のずれ：塗りを変更したり素材を追加／削除したりする前に、reference-diff.png と検証ツールの診断情報を確認します。
• 角丸アプリアイコンのマスク／フレームのずれ：frame_or_rounded_mask_residual_dominated は前景形状の失敗ではなく、フレームの正規化に関するエビデンスとして扱います。マークを修正する前に、内側の差分を確認してください。
• 局所的な大きな不一致：local_sample_gate、local_samples、tile_heatmap を読み取り、ホットスポットを具体的な修正仮説に変換します。単なる別のスコアとして扱わないでください。
• 滑らかなシンボルマーク、マスコット、ループ、リボン、ブランド風の輪郭：視覚的な誤差が曖昧な場合は、オーバーレイ／差分に加え、bbox／centroid または shape-facts を使います。
• 単純な SVG プリミティブ：修正後、影響を受けるレイヤーに対して geometry-audit を実行します。数値上の合格は、曲線の揺れ、接線の不整合、パスのノイズを許容する理由にはなりません。
• PNG フォールバック：分離した PNG アセットと png_layer_hygiene を確認します。参照画像との平均的な一致だけでは不十分です。

参照画像に基づく作業の修正順序は、まずジオメトリ／配置、次にスケール／比率、その次に色／背景、最後にレンダラー／素材感の差異です。PNG フォールバックを選ぶのは、オーバーレイ／差分／局所診断、または分離アセットの確認で、該当する SVG ルートが失敗したことを示すエビデンスがある場合に限ります。きれいに分離できるシルエットでは、PNG フォールバックの前に、該当する SVG ルートとしてコンポーネント単位でトレースした SVG を含めます。

参照先の選択

• references/source-requirements.md：出典、同一性のリスク、ソースの分類、背景のルート、PNG フォールバックのリスク。
• references/concept-prompts.md：参照元のアートワークが存在せず、画像生成またはコンセプトの直接作成が必要な場合。
• references/semantic-icon-design.md：参照画像なしの画像生成と、セマンティックな直接作成で共有する JSON デザイン契約。
• references/style-directions.md：semantic_icon_design 用の SVG に変換可能なスタイルの方向性。
• references/semantic-authoring.md：JSON 仕様の構造、semantic_review、source_analysis、レイヤーの順序、テキスト、PNG フォールバックの判断。
• references/cookbook.md：ルートが曖昧な場合、またはアイコンが幾何学的なマーク、レターフォーム、テキスト、素材の参照、重なり合うプレートなど、既知のファミリーに一致する場合。
• references/icon-composer.md：.icon の構造、塗りの形式、Icon Composer の素材の境界、アセット形式、icon.json。
• references/verification.md：検証ツールの動作、参照画像との比較、ビジュアルレビューのサイドカー、バッチの概要、レビューのゲート。
• references/optimization-methods.md：ジオメトリの仕上げ、ビットマップの抽出、形状の診断、局所的な修正、前景のクリーンアップ。
• references/failure-modes.md：汚れた PNG、誤った意味、プレビュー／塗りのずれ、ソースベクターの必要性、パスの修正、誤解を招く数値上の合格。
• references/golden-examples.md：小規模で正常な仕様とアンチパターン。
• examples/semantic-image-prompts/README.md：参照画像なしで使う画像プロンプトの例のインデックス。スタイルの方向性を決めた後、該当する例のファイルだけを読みます。

完了条件

該当するすべてのチェックを満たした場合にのみ完了とします。

• 必須のルートアセット、layers/、tmp/reports/style-report.json、および tmp/work/spec.json が存在すること。.icon/ と apple/ は、Apple アダプターが要求された場合にのみ存在します。
• ソース／参照／生成されたコンセプトがパッケージの基になっている場合、<delivery-name>.origin.png または <delivery-name>.origin.svg が納品ルートに存在し、.icon/Assets にインポートされていないこと。
• プレビューの SVG／PNG は、角丸のローカルビジュアル契約であること。ルートの SVG／PNG は、角丸にしていないアプリ／ソースキャンバスであること。
• Apple アダプターが要求された場合、許容された方法が文書化済みの PNG フォールバックでない限り、単一のフラット化されたアプリアイコンではなく、クリーンな .icon/Assets を含んでいること。
• svg_material_warnings とパッケージの warnings が空であること。png_layer_hygiene の各項目がエッジ／残留物チェックに合格していること。正当なクリーンな PNG アセットについては、配列が空でなくてもかまいません。
• 参照との一致を確認する場合、並列表示、オーバーレイ、差分を生成して確認済みであること。オーバーレイ／差分／ローカル診断を使って、修正または方法の変更を行う根拠を示していること。mean delta、visual_delta_gate、local_sample_gate がルートの目標を満たしているか、許容された意味上のトレードオフが記録されていること。
• 単純な背景が .icon/Assets 内で重複していないこと。プレビュー専用の縁、光彩、ベベル、影、ハイライト、枠線、マスクのアーティファクトがソース素材としてインポートされていないこと。

ユーザーが明示的に要求しない限り、完了範囲を Icon Composer へのインポート、アプリへの統合、公開、またはプラットフォーム固有の最終レンダリングに広げないでください。

最終回答には、納品パス、汎用ソースアセット、指定されている場合はターゲットプラットフォームのメタデータ、任意のアダプター出力、該当する場合はソースの根拠、および実際に確認したプレビュー／アセットを含めてください。インストール済みアダプターでサポートされていないネイティブエクスポートを実行または試みると主張する前に、ユーザーに確認してください。