shopify-polaris-design

このスキルでは、Shopify の Polaris Design System を使用してインターフェースを構築し、Shopify マーチャントにネイティブでアクセシブルかつプロフェッショナルな見た目と操作感を提供します。

基本原則

1. マーチャントを重視：効率性と明確さを重視して設計します。マーチャントはビジネスを運営するためにこれらのツールを使用します。
2. ネイティブな操作感：アプリは Shopify Admin の自然な拡張機能のように感じられる必要があります。よほど必要でない限り、独自のデザインパターン（Material Design のシャドウや、Bootstrap のような特徴的なボタンなど）は導入しないでください。
3. アクセシビリティ：Polaris はアクセシビリティを考慮して構築されています。カスタムの div による実装ではなく、セマンティックなコンポーネント（Button、Link、TextField など）を使用して、この特性を維持してください。
4. 予測しやすさ：Shopify の標準的なパターンに従ってください。保存ボタンは Contextual Save Bar に配置します。ページアクションは右上に配置します。主要コンテンツは中央に配置します。

技術的な実装

依存関係

• @shopify/polaris
• @shopify/polaris-icons
• @shopify/app-bridge-react（ナビゲーション、タイトルバー、トースト、保存バー用）

基本コンポーネント

• AppProvider：すべての Polaris アプリは、<AppProvider i18n={enTranslations}> でラップする必要があります。
• Page：ルートの最上位コンテナです。常に title と primaryAction（該当する場合）を設定してください。

  <Page title="Products" primaryAction={{content: 'Add product', onAction: handleAdd}}>
  

• Layout：コンテンツの構成には Layout と Layout.Section を使用します。
  • Layout.AnnotatedSection：設定ページ用です（左側にタイトル／説明、右側に Card）。
  • Layout.Section：標準の全幅（デフォルト）、1/2（variant="oneHalf"）、または1/3（variant="oneThird"）幅のカラムです。
• Card：コンテンツの主要なコンテナです。関連する情報は Card 内にまとめます。
  • Card 内のレイアウトには、BlockStack（縦方向）または InlineStack（横方向）を使用します。
  • 新しいバージョンでは非推奨のため、Card.Section は使用しないでください。代わりに gap を指定した BlockStack を使用します。

データ表示

• IndexTable：一括操作やフィルタリングを伴うオブジェクト（Products、Orders など）のリスト用です。複雑なテーブルでは、以前の ResourceList に代わって使用します。
• LegacyCard + ResourceList：テーブルヘッダーが不要なシンプルなリストでは、引き続き使用できます。
• DataTable：シンプルでインタラクティブでないデータグリッド（分析データなど）用です。
• Text：<h2> ではなく、<Text as="h2" variant="headingMd"> を使用します。タイポグラフィを厳密に制御することが重要です。

フォームの設計

• フォームフィールドの間隔と配置を自動的に調整するには、FormLayout を使用します。
• TextField、Select、Checkbox、RadioButton を使用します。
• 検証：フォームフィールドに error プロパティ（文字列またはブール値）を渡すと、検証メッセージをフィールド内に表示できます。
• ContextualSaveBar：既存のデータを編集するフォームでは、App Bridge の useSaveBar または <ContextualSaveBar> コンポーネントを使用して、変更の保存や破棄を行う専用のトップバーを表示します。

デザイントークンと CSS

• カスタム CSS を避ける：スタイルの95%は Polaris のプロパティ（gap、padding、align、justify）で設定します。
• デザイントークン：カスタム CSS を使う必要がある場合は、Polaris の CSS カスタムプロパティ（トークン）を使用します。
  • 背景：var(--p-color-bg-surface)
  • テキスト：var(--p-color-text-default)
  • 間隔：var(--p-space-400)（16px）
  • 角丸：var(--p-border-radius-200)

コードスタイルの例

import { Page, Layout, Card, BlockStack, Text, Button, InlineStack, Badge } from '@shopify/polaris';

export default function Dashboard() {
  return (
    <Page 
        title="Dashboard" 
        primaryAction={{content: 'Create Campaign', onAction: () => {}}}
        secondaryActions={[{content: 'View Logs', onAction: () => {}}]}
    >
      <Layout>
        <Layout.Section>
          <Card>
            <BlockStack gap="400">
              <InlineStack align="space-between">
                <Text as="h2" variant="headingMd">Recent Activity</Text>
                <Badge tone="success">Active</Badge>
              </InlineStack>
              <Text as="p" tone="subdued">Everything is running smoothly.</Text>
            </BlockStack>
          </Card>
        </Layout.Section>
        
        <Layout.Section variant="oneThird">
            <Card>
                <BlockStack gap="200">
                    <Text as="h3" variant="headingSm">Quick Helper</Text>
                    <Button variant="plain">Read Documentation</Button>
                </BlockStack>
            </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

避けるべきアンチパターン

• シャドウやボーダーを手動で設定しないでください。Card が処理します。
• style={{ margin: 10 }} は使用しないでください。<Box padding="400"> または <BlockStack gap="400"> を使用します。
• フォームの下部に「Save」ボタンを作成しないでください。ビューポート上部の ContextualSaveBar を使用します。
• 汎用的なローディングスピナーは使用しないでください。ローディング状態には <SkeletonPage> または <SkeletonBodyText> を使用します。