Polaris Fundamentals Skill

Purpose

Provides foundational knowledge of Polaris Web Components, including setup, component categories, design tokens, and best practices.

When This Skill Activates

•Working with Polaris Web Components
•Building Shopify app UIs
•Implementing design system patterns
•Choosing components for specific use cases

Core Concepts

Component Categories

Polaris Web Components are organized into six categories:

1. Actions - Interactive elements that trigger actions

•Buttons, links, icon buttons, button groups

2. Forms - Input and selection components

•Text fields, checkboxes, selects, file uploads, color pickers

3. Feedback - Status and notification components

•Banners, toasts, progress bars, spinners, skeletons

4. Media - Visual content components

•Avatars, icons, thumbnails, video thumbnails

5. Structure - Layout and organization components

•Pages, cards, sections, boxes, grids, stacks, tables

6. Titles and Text - Typography components

•Headings, text, paragraphs, badges, chips

Design Tokens

Spacing Scale

tsx

gap="050"  // 2px
gap="100"  // 4px
gap="200"  // 8px
gap="300"  // 12px
gap="400"  // 16px (default)
gap="500"  // 20px
gap="600"  // 24px
gap="800"  // 32px
gap="1000" // 40px
gap="1600" // 64px

Background Colors

tsx

background="bg-surface"           // Default surface
background="bg-surface-secondary" // Secondary surface
background="bg-surface-tertiary"  // Tertiary surface
background="bg-surface-success"   // Success state
background="bg-surface-warning"   // Warning state
background="bg-surface-critical"  // Error state

Border Options

tsx

border="base"     // Default border
border="success"  // Success border
border="warning"  // Warning border
border="critical" // Error border

Border Radius

tsx

borderRadius="base"  // 4px
borderRadius="large" // 8px
borderRadius="full"  // 50% (circular)

Text Tones

tsx

tone="subdued"   // Secondary text
tone="success"   // Success message
tone="warning"   // Warning message
tone="critical"  // Error message

Typography Variants

tsx

variant="heading3xl"  // Page titles
variant="heading2xl"  // Section headers
variant="headingXl"   // Card titles
variant="headingLg"   // Subsection headers
variant="headingMd"   // Card headers
variant="headingSm"   // Small headers
variant="bodyLg"      // Large body text
variant="bodyMd"      // Default body text (default)
variant="bodySm"      // Small body text

Responsive Breakpoints

tsx

// Mobile first approach
columns="1"          // Mobile (default)
sm-columns="2"       // Small devices (≥577px)
md-columns="3"       // Medium devices (≥769px)
lg-columns="4"       // Large devices (≥1025px)

// Example usage
<s-grid columns="1" md-columns="2" lg-columns="4">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
  <div>Column 4</div>
</s-grid>

React Hydration (SSR Apps)

⚠️ CRITICAL: Event Handler Pattern

NEVER use inline event handlers - they cause hydration mismatches in SSR apps.

tsx

// ❌ WRONG - Hydration mismatch
<s-button onclick={handleClick}>Click</s-button>

// ✅ CORRECT - Use data attributes + useEffect
<s-button data-my-button>Click</s-button>

useEffect(() => {
  const button = document.querySelector('[data-my-button]');
  if (button) {
    button.addEventListener('click', handleClick);
  }
  return () => button?.removeEventListener('click', handleClick);
}, []);

Common Component Patterns

Button Variants

tsx

<s-button>Default</s-button>
<s-button variant="primary">Primary</s-button>
<s-button variant="destructive">Delete</s-button>
<s-button variant="plain">Plain</s-button>
<s-button size="slim">Small</s-button>
<s-button loading>Loading</s-button>
<s-button disabled>Disabled</s-button>

Text Field States

tsx

<s-text-field
  label="Product Title"
  value={title}
  error={errors.title}        // Show error
  disabled={isDisabled}       // Disable input
  required                    // Mark required
  helpText="Customer-facing"  // Help text
  placeholder="Enter title"   // Placeholder
/>

Card Structure

tsx

<s-card>
  <s-stack gap="400" direction="vertical">
    <s-heading>Card Title</s-heading>
    <s-divider />
    <s-text>Card content</s-text>
    <s-divider />
    <s-button-group>
      <s-button variant="primary">Save</s-button>
      <s-button>Cancel</s-button>
    </s-button-group>
  </s-stack>
</s-card>

Loading Pattern

tsx

{isLoading ? (
  <s-card>
    <s-stack gap="400" direction="vertical">
      <s-skeleton-display-text />
      <s-skeleton-display-text />
      <s-skeleton-display-text />
    </s-stack>
  </s-card>
) : (
  <s-card>{/* Actual content */}</s-card>
)}

Empty State Pattern

tsx

{items.length === 0 ? (
  <s-empty-state
    heading="No items yet"
    image="https://cdn.shopify.com/..."
  >
    <s-text>Get started by adding your first item</s-text>
    <s-button variant="primary">Add Item</s-button>
  </s-empty-state>
) : (
  // Item list
)}

Page Structure

Standard Page Layout

tsx

<s-page heading="Page Title">
  <s-section>
    {/* First section */}
  </s-section>

  <s-section>
    {/* Second section */}
  </s-section>
</s-page>

Page with Primary Action

tsx

<s-page
  heading="Products"
  primaryAction={{
    content: "Add Product",
    url: "/products/new"
  }}
>
  {/* Page content */}
</s-page>

Accessibility

Semantic HTML

tsx

<s-heading as="h1">Main Title</s-heading>
<s-heading as="h2">Section Title</s-heading>
<s-text as="p">Paragraph text</s-text>

ARIA Labels

tsx

<s-icon-button
  icon="delete"
  aria-label="Delete product"
/>

<s-search-field
  aria-label="Search products"
  placeholder="Search..."
/>

Keyboard Navigation

•All interactive elements are keyboard accessible
•Use Tab to navigate
•Enter/Space to activate buttons
•Escape to close modals

Best Practices

•Use Design Tokens - Never hardcode colors, spacing, or typography
•Mobile First - Start with mobile layout, enhance for desktop
•Semantic HTML - Use the as prop for proper HTML elements
•Loading States - Always show skeleton loaders during data fetch
•Empty States - Provide guidance when no data exists
•Error Handling - Use inline errors for form validation
•Accessibility - Ensure keyboard navigation and ARIA labels
•Consistent Spacing - Use Polaris spacing scale (gap="400")
•SSR Compatible - Use data attributes for event handlers
•Follow Patterns - Use established Polaris patterns

Component Selection Guide

Need	Component	Example
Primary action	`<s-button variant="primary">`	Save, Submit
Secondary action	`<s-button>`	Cancel, Back
Destructive action	`<s-button variant="destructive">`	Delete, Remove
Page container	`<s-page>`	All pages
Content container	`<s-card>`	Forms, data displays
Text input	`<s-text-field>`	Title, description
Selection	`<s-select>`	Category, status
Multiple choices	`<s-checkbox>`	Features, options
Success message	`<s-banner tone="success">`	Saved successfully
Error message	`<s-banner tone="critical">`	Failed to save
Status indicator	`<s-badge>`	Active, Draft
Data table	`<s-table>`	Products, orders
Vertical spacing	`<s-stack direction="vertical">`	Form fields
Horizontal layout	`<s-grid>`	Dashboard cards

Documentation Reference

For complete component documentation, see:

•polaris-web-components/components/ - All component docs
•polaris-web-components/patterns/ - Composition patterns
•polaris-web-components/using-polaris-web-components.md - Setup guide

Remember: Polaris ensures your app matches Shopify's design system and provides a consistent, accessible user experience.