shopify-polaris-design

---

name: shopify-polaris-design description: Design and implement Shopify Admin interfaces using the Polaris Design System. Use this skill when building Shopify Apps, Admin extensions, or any interface that needs to feel native to Shopify.

This skill ensures that interfaces are built using Shopify's Polaris Design System, guaranteeing a native, accessible, and professional look and feel for Shopify Merchants.

Core Principles

1. Merchant-Focused: Design for efficiency and clarity. Merchants use these tools to run their business.
2. Native Feel: The app should feel like a natural extension of the Shopify Admin. Do not introduce foreign design patterns (e.g. Material Design shadows, distinct bootstappy buttons) unless absolutely necessary.
3. Accessibility: Polaris is built with accessibility in mind. Maintain this by using semantic components (e.g., Button, Link, TextField) rather than custom div implementations.
4. Predictability: Follow standard Shopify patterns. Save buttons go in the Contextual Save Bar. Page actions go in the top right. Primary content is centered.

Technical Implementation

Dependencies

• @shopify/polaris
• @shopify/polaris-icons
• @shopify/app-bridge-react (for navigation, title bar, toasts, save bar)

Fundamental Components

• AppProvider: All Polaris apps must be wrapped in <AppProvider i18n={enTranslations}>.
• Page: The top-level container for a route. Always set title and primaryAction (if applicable).

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

• Layout: Use Layout and Layout.Section to structure content.
  • Layout.AnnotatedSection: For settings pages (Title/Description on left, Card on right).
  • Layout.Section: Standard Full (default), 1/2 (variant="oneHalf"), or 1/3 (variant="oneThird") width columns.
• Card: The primary container for content pieces. Group related information in a Card.
  • Use BlockStack (vertical) or InlineStack (horizontal) for internal layout within a Card.
  • Do not use Card.Section as it is deprecated in newer versions; use BlockStack with gap.

Data Display

• IndexTable: For lists of objects (Products, Orders) with bulk actions and filtering. It replaces the older ResourceList for complex table cases.
• LegacyCard + ResourceList: Still valid for simple lists where table headers aren't needed.
• DataTable: For simple, non-interactive data grids (e.g., analytics data).
• Text: Use <Text as="h2" variant="headingMd"> instead of <h2>. Strict typography control is key.

Form Design

• Use FormLayout to automatically handle spacing and alignment of form fields.
• Use TextField, Select, Checkbox, RadioButton.
• Validation: Pass error prop (string or boolean) to form fields to show validation messages inline.
• ContextualSaveBar: For forms that edit existing data, use the App Bridge useSaveBar or <ContextualSaveBar> component to show the specialized top bar for saving/discarding changes.

Design Tokens & CSS

• Avoid Custom CSS: 95% of styling should be handled by Polaris props (gap, padding, align, justify).
• Design Tokens: If you MUST use custom CSS, use Polaris CSS Custom Properties (Tokens).
  • Backgrounds: var(--p-color-bg-surface)
  • Text: var(--p-color-text-default)
  • Spacing: var(--p-space-400) (16px)
  • Borders: var(--p-border-radius-200)

Code Style Example

Copyimport { 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>
  );
}

Anti-Patterns to AVOID

• DO NOT use Shadows or Borders manually. Cards handle this.
• DO NOT use style={{ margin: 10 }}. Use <Box padding="400"> or <BlockStack gap="400">.
• DO NOT create a "Save" button at the bottom of a form. Use the ContextualSaveBar at the top of the viewport.
• DO NOT use generic loading spinners. Use <SkeletonPage> or <SkeletonBodyText> for loading states.