Popta Template API v1

デザインテンプレート制作者ガイド

デザインフォルダ／ZIPを作成し、Poptaで検証して配布するための仕様です。バッジとポップアップは別々のフォルダとして作ります。

REFERENCE

コードと同期した資料

AIへ渡す場合も、次の資料を正本として使ってください。

完全版Markdown人とAIの両方で読める詳細仕様 AI向け指示禁止事項と成果物を短く固定 binding JSON許可された型・対象・安全範囲 CSS変数 JSON組み込みで使用確認済みの変数

01PACKAGE

パッケージ構造

my-design/
├─ design.json
├─ style.css
├─ thumbnail.png       # 任意
└─ assets/             # 任意
   └─ decoration.svg

1デザインはdesign.jsonを含む独立フォルダです。共有時は通常のZIPにします。親フォルダ付きZIPや、バッジ・ポップアップの独立フォルダをまとめたセットZIPにも対応します。各デザインの素材はそれぞれのフォルダへ入れてください。

presetとstylesheetは同じ方法で読み込まれます。Popta由来はpreset、外部作者の新規デザインはstylesheetを使用します。

02MANIFEST

`design.json`

{
  "formatVersion": 1,
  "templateApiVersion": 1,
  "id": "creator.example.simple-badge",
  "name": "シンプルバッジ",
  "kind": "stylesheet",
  "target": "badge",
  "stylesheet": "style.css",
  "defaults": {},
  "controls": []
}

idは更新でも変えない固有IDです。3〜128文字を推奨し、英数字から始まり英数字で終わるようにします。途中は英数字、ピリオド、アンダースコア、ハイフンのみ使用できます。popta.official.*は使用しないでください。

任意でauthor、description、thumbnail、license、homepageを指定できます。

03FORM

Controlsと初期値

ControlsはPoptaに表示するフォームを宣言します。任意HTMLではありません。すべてにid、type、label、sectionが必要です。

type	主な必須値
`number`	binding, min, max, step
`color`	binding
`text`	binding, maxLength
`boolean`	binding
`select`	binding, options
`font`	binding
`position`	xBinding, yBinding, xLabel, yLabel
`group`	1件以上のcontrols

defaultsには公開bindingだけを正しい型で指定します。色はhex形式です。数値の初期値はControl範囲とPopta安全範囲の両方へ収めます。

binding一覧を見る →

04CSS

Template API v1

バッジでは.badges、.cc-badge、.cc-badge-label、.cc-badge-value、.cc-badge--{itemKey}を使用します。ポップアップでは.popup-zone、.popup、.popup-text、.popup--{itemKey}を使用します。

itemKeyはlike、viewer、total、firstComment、greetingです。

html、body、:root、全称セレクタ、:is()、:where()、:has()、@importは使用できません。外部URLにもアクセスできません。

使用確認済みCSS変数を見る →

05ASSETS

画像素材

SVG、PNG、WebP、JPEGを同梱でき、assets/などのサブフォルダも利用できます。CSSの相対url(...)は読込時にData URLへ変換されます。

JavaScript、HTML、フォントファイル、ネットワーク画像は同梱できません。SVG内のscript、イベント属性、外部参照なども拒否されます。

Webフォント

Google Fonts・Bunny Fontsのみ、design.jsonの専用設定から利用できます。作者のCSSへ直接書く@import・@font-face・外部URLは引き続き禁止です。

"webFonts": [{ "provider": "google", "family": "Noto Sans JP", "weights": [400, 700] }],
"defaults": { "font": "'Noto Sans JP', sans-serif" }

上記はdesign.jsonへ追加する部分の例です。最大4件。providerはgoogle/bunny、familyは80文字以内の英数字・空白・ハイフン、weightsは100〜900の100刻みで1〜9件。通常体のみ対応します。Bunnyの例はfamily: Figtreeです。

宣言だけでは適用先は変わりません。defaults.fontまたは許可されたCSSでファミリーを指定し、代替フォントも指定してください。使用する太さ・日本語の収録有無・利用条件を確認してください。プレビューとOBSから外部通信が発生し、読み込めない場合は代替フォントになります。形式検証ではフォント名の実在や通信成功までは確認しません。

ZIP・フォルダの取り込み

右上の「読み込み」でZIPまたはdesign.jsonを選択します。設定画面の「フォルダから追加」も使えます。複数ZIPとセットZIPに対応し、Pro版で.poptaと同時選択した場合はデザインを先に処理します。

外部ファイルはAppDataへコピーし、ZIPは編集可能なフォルダへ展開します。取り込み後の修正はAppData側で行います。管理済みフォルダはコピーせず再読み込みします。

登録済みIDは上書きしません。同時選択内の重複IDは該当分をすべて除外します。識別可能な設定エラーは保存して使用不可として表示し、識別できないファイルは問題一覧へ表示します。

「デザインをリセット」はファイルを再読み込みして初期値へ戻します。横の「⋮」から再読み込み・デフォルトセットの不足ファイル復元を選べます。

06TEST

検証と配布

Popta右上の「読み込み」から追加します。
すべてのControlを最小・最大・ON/OFF・条件表示まで操作します。
5項目、横型・縦型、日本語、長い文字、ポップアップ遷移を確認します。
問題一覧が空で、プレビューとCSSコピーが動くことを確認します。
OBSへ貼り、実際のわんコメテンプレートで確認します。

開発中はデザインカードの右クリックからファイルを表示できます。修正後に「デザインをリセット」を押すと、ディスクから再読込します。

AIASSISTED CREATION

AIと一緒に作る

AIへは、見た目の要望だけでなく次の4資料を一緒に渡します。

AIに名前からbindingやCSS変数を推測させないでください。 リファレンスに存在する値だけを使い、Poptaの問題一覧とOBSで最終確認します。

一緒に伝える内容

対象がバッジかポップアップか
表示名と作者名
固有ID
作りたい見た目と変更可能にしたい項目
参考画像や近い組み込みデザイン