shopify-polaris-web-components

Shopify Polaris Web Components

Polaris Web Components を使用して Shopify App Home の画面を構築するときに、このスキルを使用します。

使用する場面

• App Home ページ（Shopify Admin の iframe の外側にあるアプリ画面）の構築
• s-* カスタム要素を使った UI の作成
• s-section、s-stack、s-box を使ったレイアウトの設計
• App Home 用のフォーム、モーダル、リストの構築

重要：App Home では Polaris Web Components（s-* 要素）を使用します。Polaris React（@shopify/polaris）ではありません。この2つは異なる技術です。

Polaris React と Web Components の比較

機能	Polaris React	Polaris Web Components
用途	埋め込み型管理アプリ	App Home の画面
インポート	@shopify/polaris	インポート不要（ネイティブ要素）
構文	<Button>	<s-button>
フレームワーク	React コンポーネント	カスタム HTML 要素

コアコンポーネント

ページ構造

<s-page heading="Dashboard">
  <s-section heading="Overview">
    
  </s-section>
  
  <s-section heading="Settings">
    
  </s-section>
</s-page>

Stack を使ったレイアウト

<s-stack direction="block" gap="large">
  <s-text>Item 1</s-text>
  <s-text>Item 2</s-text>
</s-stack>


<s-stack direction="inline" gap="medium" alignItems="center">
  <s-button>Cancel</s-button>
  <s-button variant="primary">Save</s-button>
</s-stack>


<s-stack 
  direction="inline" 
  justifyContent="space-between"
  alignItems="center"
>
  <s-text variant="headingMd">Title</s-text>
  <s-button>Action</s-button>
</s-stack>

Section（カード風コンテナ）

見出しを任意で付けられるグループ化されたコンテンツには、s-section を使用します。

<s-section heading="Chat Widget Settings">
  <s-stack direction="block" gap="medium">
    <s-text>Configure your widget appearance.</s-text>
    
  </s-stack>
</s-section>


<s-section>
  <s-text>Simple content block</s-text>
</s-section>

Box（汎用レイアウトコンテナ）

パディング、枠線、間隔の設定には s-box を使用します。カードには使用しません。

<s-box padding="large">
  <s-text>Padded content</s-text>
</s-box>


<s-box 
  padding="medium" 
  borderWidth="base" 
  borderRadius="base"
>
  <s-text>Bordered content</s-text>
</s-box>


<s-box paddingBlockStart="large">
  <s-text>Content with top margin</s-text>
</s-box>

ルール：カード風コンテナには s-section を使用し、レイアウトや間隔の設定には s-box のみを使用します。

ボタン

<s-button variant="primary" type="submit">
  Save Settings
</s-button>


<s-button>Cancel</s-button>


<s-button variant="primary" tone="critical">
  Delete
</s-button>


<s-button disabled>Unavailable</s-button>


<s-button id="save-btn">Save</s-button>
<script>
  document.getElementById('save-btn').addEventListener('click', handleSave);
</script>

テキスト

<s-text variant="headingLg">Large Heading</s-text>
<s-text variant="headingMd">Medium Heading</s-text>
<s-text variant="headingSm">Small Heading</s-text>


<s-text>Default body text</s-text>
<s-text variant="bodySm">Small body text</s-text>


<s-text tone="subdued">Muted text</s-text>
<s-text tone="critical">Error text</s-text>
<s-text tone="success">Success text</s-text>

バナー

<s-banner>
  <p>This is an informational message.</p>
</s-banner>


<s-banner tone="critical">
  <p>Something went wrong. Please try again.</p>
</s-banner>


<s-banner tone="success">
  <p>Settings saved successfully!</p>
</s-banner>


<s-banner tone="warning" onDismiss="handleDismiss">
  <p>Your trial ends in 3 days.</p>
</s-banner>

リンク

<s-link href="/settings">Go to Settings</s-link>

<s-link href="https://shopify.dev" external>
  Documentation
</s-link>

フォーム要素

<s-text-field 
  label="Store name"
  value="My Store"
  helpText="This appears in your widget"
></s-text-field>


<s-select label="Language">
  <option value="en">English</option>
  <option value="es">Spanish</option>
</s-select>


<s-checkbox label="Enable notifications" checked></s-checkbox>

よく使われるパターン

設定ページ

<s-page heading="Settings">
  <s-stack direction="block" gap="large">
    
    <s-section heading="General">
      <s-stack direction="block" gap="medium">
        <s-text-field 
          label="Welcome message"
          value="Hello! How can we help?"
        ></s-text-field>
        <s-checkbox label="Enable auto-reply"></s-checkbox>
      </s-stack>
    </s-section>
    
    <s-section heading="Appearance">
      <s-stack direction="block" gap="medium">
        <s-select label="Theme">
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </s-select>
      </s-stack>
    </s-section>
    
    <s-box paddingBlockStart="large">
      <s-stack direction="inline" gap="medium" justifyContent="flex-end">
        <s-button>Cancel</s-button>
        <s-button variant="primary">Save</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-page>

空の状態

<s-section>
  <s-stack direction="block" gap="medium" alignItems="center">
    <s-text variant="headingMd">No campaigns yet</s-text>
    <s-text tone="subdued">
      Create your first campaign to get started.
    </s-text>
    <s-button variant="primary">Create Campaign</s-button>
  </s-stack>
</s-section>

アクション付きリスト

<s-section heading="Campaigns">
  <s-stack direction="block" gap="none">
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">Welcome Series</s-text>
          <s-text tone="subdued">Active • 1,234 sent</s-text>
        </s-stack>
        <s-button>Edit</s-button>
      </s-stack>
    </s-box>
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">Abandoned Cart</s-text>
          <s-text tone="subdued">Paused • 567 sent</s-text>
        </s-stack>
        <s-button>Edit</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-section>

TypeScript のサポート

tsconfig.json に s-* コンポーネントの型を追加します。

{
  "compilerOptions": {
    "types": ["@shopify/polaris-types"]
  }
}

ベストプラクティス

1. カードには s-section を使用する - s-box は使用しません
2. レイアウトには s-box のみを使用する - パディング、枠線、間隔の設定
3. カスタム div より s- を優先する* - s-* でレイアウトを実現できない場合にのみ div を使用します
4. セマンティックな構造を使用する - s-page > s-section > content
5. 間隔を統一する - 手動でマージンを指定せず、gap プロパティを使用します
6. ドキュメントを確認する - ここで紹介していないプロパティも多数あります

カスタムスタイルを使用する場面

次の場合にのみ、プレーンな div とインラインスタイルを使用します。

• ユーザーから明示的に要求された場合
• s-* コンポーネントを試しても、必要なレイアウトを実現できない場合
• Polaris でサポートされていない、非常に特殊な視覚効果を使う場合

参考資料

• Polaris Web Components
• Polaris コンポーネントの使用
• App Home の概要
• コンポーネントリファレンス