suggest-icon

Font Awesome アイコンに関する既存の知識は、最初の候補を素早く考えるのに役立ちますが、バージョンによっては不正確な場合があります。信頼できる回答をするため、複数の情報源を組み合わせてください。

以下のスクリプトはすべて、このスキルのディレクトリ（plugins/icons/skills/suggest-icon/）からの相対パスです。スクリプトはこのディレクトリから実行してください。

ツールの選択

最初に command -v fa を実行して、fa CLI が PATH 上で利用できるか確認してください。

fa kit サブコマンドには、バージョン 0.8.0 以降の fa が必要です。fa kit サブコマンドが必要な場合は、こちらの手順に従って fa をアップグレードするようユーザーに案内してください：https://docs.fontawesome.com/web/use-with/fa-cli

• fa が見つかった場合： アイコンの参照と検索に使用してください（構造化 JSON が返されます）。プロジェクトで Kit が設定されている場合（「設定済みの Kit を尊重する」を参照）は、Kit で利用できるアイコンだけを検索するため fa search --kit-token <TOKEN> も使用し、特定のアイコンが含まれているか確認するために fa kit icon を使用してください。fa kit ... の操作では、まず認証を確認してください（fa whoami または FA_API_TOKEN）。認証できない場合は、Kit に絞り込まない検索に切り替え、Kit の対象範囲を確認できなかったことをユーザーに伝えてください。
• fa が見つからない場合： 以下で説明する Python スクリプトに切り替えてください。Kit を考慮した検索には fa CLI が必要です。これがない場合、提案を Kit 内のアイコンに絞り込むことはできないため、提案したアイコンがユーザーの Kit に含まれていない可能性があることを伝えてください。
• 最新バージョンの取得には latest-version.py を使用してください。

設定済みの Kit を尊重する

プロジェクトに Kit ID（Kit トークン）が記載された .font-awesome.md ファイルがある場合、ユーザーのアイコンはその Kit から取得されます。Kit に含まれるのは Font Awesome の全アイコンの一部だけです。Kit に含まれていないアイコンは提案しないでください。 Kit にないアイコンを推奨すると、アイコンが表示されない結果になります。

Kit トークンがある場合は、すべての候補を Kit 内のアイコンに絞り込んでください。

• fa search --version <version> ... ではなく、fa search --kit-token <TOKEN> --query <your-guess> で検索してください。Kit の対象範囲内で実際に利用できるアイコンだけが返されるため、すべて安全に推奨できます。
• 第一候補を提示する前に、fa kit icon --kit-token <TOKEN> <icon> で確認してください。これにより、そのアイコンが Kit に含まれているか、利用可能なファミリーとスタイルが分かります。
• 推奨したいアイコンが Kit に含まれていない場合は、そのことを明確に伝え、代わりに Kit で利用できる最も近いアイコンを提案してください。また、不足しているアイコンを https://fontawesome.com/kits から Kit に追加でき、追加後は利用可能になることをユーザーに伝えてください。

.font-awesome.md が存在しない場合、または Kit の記載がない場合は、通常どおり全アイコンセットから提案してください。

手順

1. バージョンを決定します。 ユーザーが Font Awesome のバージョンを指定している場合は、それを使用します。指定がない場合は、最新バージョンを使用します（上記の「ツールの選択」を参照）。以降のすべての手順では、決定したバージョンを使用します。

   また、プロジェクトのルートに .font-awesome.md ファイルがあるか確認します。Kit ID（Kit トークン）が記録されている場合は、手元に控えておきます。検索と提案の範囲をその Kit に限定します（上記の「設定済みの Kit を尊重する」を参照）。

2. 最初の候補を考えます。 用途の説明に最も合うと思うアイコン名を、知識に基づいて選びます。

3. アイコンの存在を確認します。

   • fa CLI： fa icons --version <version> --name <your-guess> を実行します。data.release.icon が null でなければ、そのアイコンは存在します。familyStylesByLicense フィールドには、無料版と Pro 版の内訳が表示されます。
   • フォールバック： ./scripts/icon-exists.py --version <version> --icon-name <your-guess> を実行します。終了コード 0 はアイコンが存在することを、終了コード 1 は存在しないことを意味します。

   Kit トークンが設定されている場合は、 fa kit icon --kit-token <TOKEN> <your-guess> を実行して、そのアイコンが Kit に含まれていることも確認します。Font Awesome に存在するアイコンでも、Kit のサブセットに含まれていないことがあります。Kit にないアイコンは、そのままでは推奨しないでください（手順 5 を参照）。

4. 代替案を検索します。 最初の候補が存在するかどうかにかかわらず、必ず検索してください。検索によって、自分では思いつかなかった、より具体的で用途に合うアイコンが見つかることがあります。

   • Kit が設定済み（fa CLI）： fa search --kit-token <TOKEN> --query <your-guess> --page-size 10 を実行します。Kit で使用できるアイコンのみが返されるため、すべての結果を安心して推奨できます。Kit トークンがある場合は、常にこの方法を優先してください。
   • Kit なし（fa CLI）： fa search --version <version> --query <your-guess> --page-size 10 を実行します。結果は data.searchPaginated.icons[] にあり、それぞれ id、label、unicode、familyStylesByLicense を含みます。
   • フォールバック： ./scripts/search.py --version <version> --query <your-guess> を実行して、Font Awesome GraphQL API から関連するアイコンを検索します。（この方法では Kit のサブセットに検索対象を限定できません。）

5. 推奨を提示します。 最も適したアイコンを第一候補として選び、検索で他にも良い候補が見つかった場合は、関連する代替案も含めます。Kit が設定されている場合は、すべての推奨アイコンがその Kit に含まれていなければなりません。概念的に最適なアイコンが Kit に含まれていない場合は、Kit で使用できる最も近い代替案を推奨し、不足しているアイコンは https://fontawesome.com/kits から Kit に追加できることを伝えます。次の例のような Markdown テーブルを使用します。

   アイコン	ファミリー	利用可否
   mug-saucer	classic, sharp, duotone, sharp-duotone	無料

   Pro 限定の場合は、Font Awesome のサブスクリプションが必要であることを記載します。

   アイコン	ファミリー	利用可否
   album-collection	classic, sharp, duotone, sharp-duotone	Pro（サブスクリプションが必要）

6. SVG マークアップをそのまま提供しないでください。 ユーザーがアイコンの生の <svg> 出力を求めた場合は、自分の知識に基づいて生成しないでください。代わりに /add-icon を使用するよう案内してください。/add-icon は fa icons --svg-format を介して Font Awesome API から正規の SVG マークアップを取得できます。

7. アイコンの追加を提案します。 推奨を提示した後、ユーザーに「このアイコンをコードに追加しますか？」と尋ねます。ユーザーが「はい」と答えるか、場所を指定した場合は、推奨したアイコン名（場所が指定されていればその場所も）を指定して /add-icon を呼び出します。