page-mascot

マスコット

「ページにキツネを載せて」や「ちびカワウソを描いて」を、動作する <Mascot /> にします。

キャラクターはそれぞれ、3×3のスプライトシート2枚で構成されています。1枚には9方向の頭部、もう1枚には9種類の表情が描かれています。コンポーネントは background-position を動かしてシートを切り替えるため、フレームごとの JavaScript もアニメーションライブラリも不要です。キャラクターは2つのファイルだけで構成されており、レジストリはなく、名前を把握しておく必要もありません。

どちらの方法を選ぶか

• ユーザーがキャラクターを指定した、または既存のキャラクターでよい場合 -- 描画済みのものを使います。Python も API キーも不要で、どの React プロジェクトでも動作します。こちらが一般的なケースです。
• ユーザーが新しいキャラクターや、自分に似せたものを求めている場合 -- 新しく描画します。その後、ページに配置します。

どちらの方法でも、最後は ページに配置します。ファイルとコードスニペットを用意しただけで終わらせないでください。

描画済みのものを使う

1. 選びます。 reference/characters.md にある52種類から選びます。ユーザーが指定していない場合は、サイトに合うものを選び、何を選んだか、またその理由を伝えてください。

2. 2枚のシートを取得します。 このプロジェクトで静的ファイルを配信する場所に保存します。Next、Vite、CRA、Astro では public/、SvelteKit では static/ を使います。または、コンポーネントの隣に置いてインポートします。

   mkdir -p public/mascots
   curl -fsSL -o public/mascots/fox-directions.webp https://koboyo.com/page-mascot/mascots/fox-directions.webp
   curl -fsSL -o public/mascots/fox-reactions.webp  https://koboyo.com/page-mascot/mascots/fox-reactions.webp
   

3. ページに配置します（下記）。

ページに配置する

コンポーネントをインストールします。 ロックファイルが示すパッケージマネージャーを使います。 npm i page-mascot、pnpm add page-mascot、yarn add page-mascot、または bun add page-mascot を実行してください。パッケージ管理されている React プロジェクトではない場合は、代わりにこの SKILL.md と同じ場所にある mascot.tsx をプロジェクトにコピーしてください。ファイルは1つだけで、React のみが必要です。また、インラインスタイルを使用します。

描画します：

import { Mascot } from 'page-mascot'

<Mascot
  directions="/mascots/fox-directions.webp"
  reactions="/mascots/fox-reactions.webp"
/>

directions と reactions は、配信する2枚のシートのパス、またはインポートした画像です。どちらも必須です。その他の props は、size（デフォルトは140）、label（スクリーンリーダーが読み上げる名前）、className です。

ユーザーが指定した場所に配置します。 指定がない場合はページの上部、つまりヘッダーまたはヒーロー領域のタイトルの上か横に配置します。カーソルを見つめる頭部を表示するのに最適な場所です。実際のコンポーネントを編集し、変更した内容と場所をユーザーに伝えてください。

新しく描画する

まず、描画方法を決めます

キャラクターごとに2枚のシートを描画する必要があり、それを自力で行えるかどうかはエージェントによって異なります。次の順に確認してください。

1. 組み込みの画像生成ツールがある場合（Codex にはあります）。そのツールを直接使い、以下の 自分で描画する に従ってください。まず、背景を透明にして出力できるか確認してください。それによって送るプロンプトが決まります。オプションがある場合は、透明にするよう指示して設定してください。オプションがない場合は、単色のキー色で描画し、あとからその色を削除します。どちらの方法も 透明化 に記載されています。
2. OPENAI_API_KEY が設定されている場合。画像ツールを必要としない API 経由の方法を使い、以下の API 経由で描画する に従ってください。画像ツールを持たない Claude Code にはこの方法が適しています。generate.py は API の background パラメーターで透明化を要求し、アルファチャンネルが返されない場合は自動的にキー色を使う方法に切り替えます。
3. どちらも該当しない場合。描画には画像を生成できるエージェントか OPENAI_API_KEY のどちらかが必要だと明確に伝え、代替案を2つ提示してください。1つは、すでに描画済みの52キャラクターのいずれかを使うこと（描画済みのものを使う）、もう1つは reference/prompts.md にある手動の方法で、ユーザー自身がプロンプトをチャット UI に貼り付けることです。回避策として、ブラウザーで Web UI を操作しようとしないでください。ページのマークアップに依存し、ログイン済みのセッションが必要で、セットの途中でレート制限に達するためです。

いずれの方法でも、ビルドには Python 3 が必要です。

python3 -c "import PIL, numpy, scipy" 2>&1

失敗した場合：pip install -r <skill-dir>/scripts/requirements.txt を実行してください。回避策を試さず、ここで停止してその旨を伝えてください。

以下で使う <skill-dir> は、SKILL.md が置かれているフォルダーです。このスキルは通常、プロジェクトの外にインストールされているため、フルパスを使用してください。すべてのコマンドはプロジェクトのルートから実行してください。スクリプトは characters/<name>/ から元のシートを読み込み、現在のディレクトリにある public/mascots/ にビルド済みのアトラスを書き込みます。public/ が静的ファイルの配信先ではない場合は、--dest static/mascots（またはこのプロジェクトの静的ファイル配信先）を指定してください。

API 経由で描画する

1つのコマンドで、生成、チェック、ビルド、検証、再試行を行います。

python3 <skill-dir>/scripts/mascot.py fox --describe "a chibi fox with warm orange fur, a cream muzzle and dark ear tips"

見た目を変えるには --style riso を追加し、人物を描き直すには --reference ~/photo.jpg を追加してください。--only reactions を指定すると、表情シートだけを描き直し、動作シートはそのまま残します。モデルがアルファチャンネルを返さない場合、そのシートを単色のキー色で描き直して色を削除します。そのため、画像が1枚余分に必要になります。最初からキー色を使うには --key green を指定してください。上記のパッケージに加えて pip install openai が必要です。画像モデルは generate.py で固定されています。別のモデルを使うには MASCOT_IMAGE_MODEL を設定してください。

自分で描画する

1. 動作シートを描画します。 画像生成ツールを使い、reference/prompts.md にある DIRECTIONS プロンプトのキャラクターの説明を差し替えてください。ツールで背景を透明にできない場合は、代わりにそのプロンプトのキー色版を送り、オプションをオフにしてください。以下の 透明化 を参照し、両方のシートに同じ版を送ってください。characters/<name>/directions.png に保存してください。

2. 表情シートを描画します。 EXPRESSIONS プロンプトを使い、先ほど作成した動作シートを参照画像として渡してください。characters/<name>/reactions.png に保存してください。

3. ビルドして検証します。

python3 <skill-dir>/scripts/mascot.py <name> --skip-generate

4. 結果に応じて対応します。 完了してキャラクターの準備ができたと表示されるか、2枚のうちどちらのシートに問題があるかが示されます。問題のあるシートを描き直し、手順3をもう一度実行してください。2回試しても解決しない場合は、説明を変更してあきらめてください。それ以上はビルドではなく、アートの問題です。

コマンドは自分で実行してください。ユーザーがコピーできるように表示してはいけません。

頭の向きが正しい方向を向いているか確認する

スクリプトでは、キャラクターが実際にどちらを向いているか以外はすべて測定できます。 キャラクターを引き渡す前に、方向シートのleftセル（中央の行、左端の列）と rightセル（中央の行、右端の列）を切り抜いて確認してください。左のセルは、見る人から見て左を向いている必要があります。

シートが左右反転した状態で生成されることがあります。その場合、ページ上のカーソルから目をそらしているように見えても、すべてのチェックで満点になります。再生成する必要はありません。アートは正しく、セルの順序だけが間違っています。reference/design-rules.mdにある3行の列入れ替えで修正できます。

透明度は最もよく問題が起きる点です

シートは必ず、実際のアルファチャンネルを持つPNGにする必要があります。プロンプトでは実現できません。透明度は画像生成の呼び出し時に設定するものです。OpenAI APIならbackground: "transparent"、組み込みツールなら同等のオプションを指定します。言葉で指示されたからといって、モデルが透明にするわけではありません。gpt-image-2.5で15枚のシートを測定したところ、オプションを設定すれば、プロンプトで透明度に一切触れていなくても、すべてのシートに実際のアルファチャンネルが含まれていました。設定しなければ、すべてのシートでキャラクターの背後に描画された灰色と白のチェッカーボードが表示されました。大文字で「本物のアルファチャンネルを持つPNGに……白ではなく」と求めたプロンプトも同様です。アルファチャンネルを出力できないモデルは、それを表す模様を描きます。

つまり、プロンプトは2種類あり、どちらを送るかはキャラクターではなくツールによって決まります。

• ツールが透明な背景を返せる場合。 そのオプションを設定し、reference/prompts.mdのプロンプトをそのまま使います。

• 返せない場合。 透明度を求めることだけは避けてください。そうするとチェッカーボードが出てしまうからです。チェッカーボードは復元できません。マス目がキャラクターの輪郭の下まで入り込んでいます。代わりに、プロンプトのキー用バリエーション（reference/prompts.mdの透明度なしで描画する）を送ります。こちらは単色の純粋な緑色の背景を求め、透明度には一切触れません。その後、この緑色を取り除きます。

  python3 <skill-dir>/scripts/key.py characters/<name>/directions.png --in-place
  

  mascot.pyは、シートの背景が単色のキー色だと判別すると自動で処理するため、通常はビルドを実行するだけで構いません。

曖昧な指示ではうまくいきません。「透明にできない場合は緑色を使う」と付け加えて透明度を求めるプロンプトも、以前と同じようにチェッカーボードを生成します。2種類のプロンプトは代替手段であり、決して組み合わせてはいけません。

screen.pyに、どちらのケースに該当するかが表示されます。

表示内容	起きたこと	対処方法
alpha: ok	実際のアルファチャンネルがある	何もしない
alpha: MISSING (solid #02F902 background -- key.py can remove it)	キー色で描画された	キーアウトするか、mascot.pyに処理させる
alpha: MISSING (painted checkerboard, 32px squares -- redraw)	ツールでは実現できない透明度を求めた	ツールに合ったプロンプトで描き直す
alpha: MISSING (opaque background)	白またはシーンの背景に統合された	描き直す。この状態からキーアウトできるものはない

最後の2つは修復できません。白い背景はキーアウトできません。キャラクター自体のクリーム色や白い部分も一緒に消えてしまうからです。そのため、キー色には彩度の高い緑色を使い、白、灰色、黒は使いません。

説明文を書く

仕上がりの良し悪しを左右するため、ユーザーの言葉をそのまま渡すのではなく、説明文を一文加えてください。「fox」よりも、「暖かみのあるオレンジ色の毛並み、クリーム色の口元、濃い色の耳先が特徴のかわいいちびキツネ」のほうがよい仕上がりになります。色と、見分けるための特徴を2つか3つ、一文で挙げてください。

次の要素は、この効果に欠かせない位置合わせを崩すため、避けてください。

• 肩にかかる長いストレートヘア。 髪を結ぶか、帽子の下に入れてください。シートごとに描かれ方が変わり、クリックしたときにマスコットがよろめきます。最もよくある失敗です。
• 頭より幅の広いもの。 大きな翼や幅広の頭飾りなどです。セルの端で切れてしまいます。
• 手に持つ小道具。 杖、マグカップ、楽器などです。フレームに入るのは頭と肩だけです。

よい例：a chibi robot with a mint-green boxy head and a single wide visor screen、a chibi grandmother with silver hair in a neat bun and round gold spectacles。

別のスタイルで描く

スタイルは6種類あります。colour（デフォルト）、ink、sketch、riso、paper、pixelです。変わるのはキャラクターの描き方だけです。フレーム、プロポーション、共通のボディ、余白は共通なので、スタイルによって位置合わせが崩れることはありません。

reference/prompts.mdに各スタイルの段落があります。そのキャラクターの両方のプロンプトで差し替え、2枚目のシートがデフォルトのスタイルに戻らないよう、EXPRESSIONSプロンプトでもスタイルを再度指定してください。API経由の場合はフラグで指定します。

python3 <skill-dir>/scripts/mascot.py fox --style riso --describe "a chibi fox with orange fur"

そのキャラクターの2枚のシートでは、同じスタイルを使ってください。ink、sketch、pixelの注意事項はreference/prompts.mdの末尾にあります。この3つを使う前に確認してください。

ユーザー自身の画像を使う

基本的な手順は同じですが、ステップ1ではreference/prompts.mdにあるREFERENCEプロンプトとともに、ユーザーの画像を画像ツールに渡してください。パイプラインで必要なスタイルに合わせて、画像のキャラクターを描き直した設定シートが作成されます。ステップ2以降は変わりません。

その後

生成されたアトラスはpublic/mascots/<name>-{directions,reactions}.webp（または--dest）に保存されます。キャラクターを描き直さずに再生成できるよう、元のシートはcharacters/<name>/に残ります。そのことを伝えたうえで、残すか削除するかはユーザーに任せてください。

続いて、ページに配置します。

複数作る場合

一度に1つずつ作成し、進捗をその都度報告してください。

さらに詳しく

reference/design-rules.mdでは、それぞれの作画ルールが必要な理由、各失敗例の見た目、2枚のシートの合わせ方について説明しています。スクリプトのメッセージではカバーされない問題がキャラクターに起きた場合は、こちらを確認してください。