salla-embedded-ui

Salla Embedded UI

埋め込みアプリのネイティブなルック＆フィール — Embedded SDK のデザインシステム上に表示される、マーチャントダッシュボードの iframe です。このスキルが扱うのはネイティブなスタイリングのみであり、ここに記載するガイダンスは参考情報ではなく、必ず従うべき指示です。以下の各ルールは必須要件であり、省略すると、マーチャントのダッシュボードに場違いな見た目の iframe が組み込まれてしまいます。「表示される」だけでは不十分です。「ライト／ダークの両テーマと RTL でネイティブに見え、実際のスクリーンショットで確認できている」ことが基準です。

ストアフロント UI は別のデザインシステムです → salla-storefront-ui。 SDK の起動、ページ登録、認証については → salla-embedded-app。

⛔ 管理者による却下について これらは Salla の公式デザインガイドラインです。明らかに違反しているアプリは、管理者レビューで却下される場合があります。以下の各チェックポイントは提案ではなく、管理者による審査項目として扱ってください。

このスキルが適用される範囲

ダッシュボード iframe 内の、ユーザーに見えるすべての UI が対象です。embedded.init() の設定、ページの登録、認証トークンの検証を行う場合は、salla-embedded-app の対象です。UI を描画する段階になったら、ここに戻ってください。一般的な知識をもとにスタイルを設定し、あとから修正するのではなく、最初のマークアップからこれらのルールに沿って UI を構成してください。

認証は必須であり、このスキルの対象外です。 マーチャント向けのすべてのインターフェース（iframe と、そこから呼び出されるバックエンド）は、認証済みでサーバー検証済みのセッションで動作させる必要があります。iframe のコンテキストだけを信頼してはいけません。セッション／トークンの検証については salla-embedded-app、OAuth／マーチャントトークンについては salla-app-auth を参照してください。このスキルが扱うのはルック＆フィールのみです。

---

ステップ 0 — 正式なデザインガイドラインを読み込む（最初に行うこと）

マークアップを書く前に、唯一の正式なトークン／パターンのソースを読み込み、すぐ参照できる状態にしてください： ../salla-embedded-app/references/design-guidelines.md — ブランドカラーのトークン（ライト／ダークの HEX と HSL）、PingARLT のタイポグラフィスケール、4px のスペーシンググリッド、Hugeicons、No-Chrome ルール、コンポーネントパターン（カード／ボタン／ページ）、Do/Don't 表が記載されています。トークンの値を独自に決めたり、ブランドのティールを推測したり、コンテキストの圧縮をまたいで色を記憶に頼ったりしないでください。必ずこのファイルを参照してください。 ライブドキュメント：https://docs.salla.dev/embedded-sdk/design-guidelines.md · プレイグラウンド https://docs.salla.dev/embedded-sdk/playground.md

ステップ番号に関する注意： design-guidelines.md は salla-embedded-app 用に作成されています。このファイル内の「SKILL.md Step N」という参照は、このスキルではなく、_その_スキルのステップを指しています。 認証／セッションについては salla-embedded-app のステップ 3、テーマの設定についてはこのスキルのステップ 1を参照してください。

チェックポイント： design-guidelines.md を読み込み、記憶や推測による値ではなく、記載された正確なトークン／パターンを使用していますか？

---

ステップ 1 — embedded.init() からテーマ、ロケール、方向を設定する

テーマ／ロケール／dir は、embedded.init() の layout から取得してください（salla-embedded-app のステップ 4 を参照）。自分で解析したクエリパラメーターから取得してはいけません。初期化時に <html> の dir／lang／data-theme を設定し、embedded.onThemeChange の実行時と、再初期化／リフレッシュのたびに再適用してください。

チェックポイント： dir、lang、data-theme はすべて layout から取得し、テーマのライブ切り替え時に再適用されていますか？

---

ステップ 2 — SDK モジュールによるネイティブのクローム（No-Chrome ルール）

iframe はダッシュボード独自のクローム内に配置されています。作り直さないでください。 iframe 内に独自の UI を実装するのではなく、ホストレベルの操作にはすべて SDK モジュールを使用してください。

• タイトル → embedded.page.setTitle()（iframe 内にページヘッダーを配置しないでください）。
• 主なアクション → embedded.nav.setAction()（ページ内に重複する保存ボタンを配置しないでください）。
• フィードバック → embedded.ui.toast / embedded.ui.confirm() / embedded.ui.loading.show() + .hide()（window.confirm()、独自のトーストオーバーレイ、独自のスピナーは使用しないでください）。
• パンくずリスト → 集中表示／フルブリードのフローでは embedded.ui.breadcrumbs.hide() を使用し、 終了時に復元するには embedded.ui.breadcrumbs.show() を使用してください。iframe 内にパンくずリストを配置しないでください。
• サイドバーも iframe 内のトップナビゲーションバーも不要です。コンテンツはコンテナー全体に広がるフル幅にします。

生の postMessage ではなく、SDK メソッドを呼び出してください。モジュールのリファレンス → ../salla-embedded-app/references/sdk-modules-guide.md。

ゲート： 独自のサイドバー／ナビゲーションバー／パンくずリスト／確認ダイアログ／トーストを使わず、すべてを page／nav／ui の SDK メソッド経由で処理していますか？

---

ステップ 3 — ダッシュボードに合わせる：トークン、書体、間隔、アイコン

アプリがダッシュボードのネイティブなセクションと見分けがつかないよう、デザインガイドラインのトークンに基づいてスタイルを設定してください。

• 色 — ダッシュボードのブランドトークン（--color-primary のティール、--color-danger など）を使用し、ライトモードとダークモードの両方を定義します。ブランドに合わない色をハードコードしないでください。
• タイポグラフィ — PingARLT のフォントスタック、ベースサイズ 14px、text-xs…text-xl のスケールを使用します。
• 間隔 — 4px グリッド（space-1…space-8）を使用します。
• アイコン — Hugeicons のみを使用します（hgi hgi-stroke hgi-*）。ストロークの太さを統一し、SDK の nav.setAction が想定するクラスに合わせます。
• コンポーネント — design-guidelines.md のカード／ボタン／ページのパターンを使用し、border-radius、border、シャドウを正確に合わせます。独自の形状は使用しないでください。
• 文言 — 表示されるすべてのラベルを ar と en の両方で用意します。アラビア語を使用するマーチャント向けに英語のみの表示をしないでください。

ゲート： すべての色／フォント／間隔／アイコンがデザインガイドラインのトークンに基づき、すべてのコンポーネントの形状がデザインガイドラインのパターンに一致し、ライトモードとダークモードの両方で読みやすく、表示されるすべてのラベルに ar と en の文言がありますか？

---

ステップ 4 — RTL の正確性（アラビア語優先）

マーチャントの大半はアラビア語を使用するため、RTL は例外的なケースではなくデフォルトです。どこでも CSS の論理プロパティ（margin-inline-start、padding-inline、border-inline-start）を使用してください。left／right や、グローバルな text-align: left は使用しないでください。LTR だけでなく dir="rtl" でも確認してください。

ゲート： dir="rtl" でレイアウトが正しく反転し、left／right の物理プロパティもグローバルな text-align: left も使われていませんか？

---

ステップ 5 — インストール済みのデモストアで LIVE 確認する（必須）

コードが実行できることは、見た目が正しいことの証明にはなりません。完了を宣言する前に、以下を行ってください。

1. salla_apps action=demo_stores を実行し、ストアの install_url を開いてから、その dashboard_url を開きます。
2. 作成した埋め込みページを、実際のダッシュボード内でスクリーンショットに撮ります。
3. そのスクリーンショットで、コンプライアンスレポートのテンプレートに照らして確認します。

ゲート（最終確認）： 「インストール済みのデモストアで、この埋め込みページを LIVE スクリーンショットに撮り、ネイティブの SDK クローム + Hugeicons + ダッシュボードのトークン + 正しい RTL を、ライトモードとダークモードの両方で確認しましたか？コードが実行できただけではありません。」

references/compliance-report-template.md のテンプレートを使用してコンプライアンスレポートを出力し、LIVE スクリーンショットに基づいて各チェックポイントに ✅/❌ を記入して、開発者に返してください。

注意すべき落とし穴

つい考えてしまうこと	それが間違っている理由
「表示できてコードも動くから、これで完了です。」	描画されること ≠ ネイティブであることです。証明となるのは、ステップ 5 の実際のスクリーンショットだけです。
「Salla のティールはよく知っているので、色コードを入力できます。」	推測や記憶に頼った16進数カラーコードはブランドカラーからずれ、ダークモードで問題を起こします。ステップ 0 で design-guidelines.md のすべてのトークンを確認してください。
「iframe に小さなヘッダーや保存ボタンを追加します。」	ダッシュボードを入れ子にするアンチパターンです。タイトルには page.setTitle、アクションには nav.setAction を使ってください。No-Chrome は必須です（ステップ 2）。
「今のところは window.confirm() や独自のトーストで問題ありません。」	UX が断片化します。必ず SDK のメソッドである ui.confirm()、ui.toast、ui.loading.show() を使ってください（ステップ 2）。
「英語で動作してから RTL に対応します。」	RTL は加盟店にとって標準的なケースです。最初から論理プロパティを使ってください（ステップ 4）。
「ライトモードでは問題なさそうなので、リリースします。」	ダークモードは実際に切り替わります。完了前に両方のテーマで読みやすさを確認する必要があります（ステップ 3 とステップ 5）。
「英語のラベルでアラビア語を使う加盟店にも十分伝わります。」	アラビア語が標準言語です。すべてのラベルに ar の文言が必要です。英語のみではバイリンガル対応の基準を満たしません（ステップ 3）。

---

リソース

トピック	リンク
公式トークン／パターン（最初に読み込む）	../salla-embedded-app/references/design-guidelines.md
SDK モジュール（page/nav/ui）	../salla-embedded-app/references/sdk-modules-guide.md
デザインガイドライン（最新）	https://docs.salla.dev/embedded-sdk/design-guidelines.md
プレイグラウンド／テスト	https://docs.salla.dev/embedded-sdk/playground.md