polaris-fundamentals

name	polaris-fundamentals
description	Core Polaris Web Components fundamentals including component library structure, design tokens, responsive patterns, and SSR compatibility. Auto-invoked when working with Polaris components.
allowed-tools	["Read","Grep","Glob"]
documentation_path	../../../polaris-web-components

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

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

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

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

Border Radius

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

Text Tones

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

Typography Variants

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

// 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.

// ❌ 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

<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

<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

<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

{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

{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

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

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

Page with Primary Action

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

Accessibility

Semantic HTML

<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

<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

1. Use Design Tokens - Never hardcode colors, spacing, or typography
2. Mobile First - Start with mobile layout, enhance for desktop
3. Semantic HTML - Use the as prop for proper HTML elements
4. Loading States - Always show skeleton loaders during data fetch
5. Empty States - Provide guidance when no data exists
6. Error Handling - Use inline errors for form validation
7. Accessibility - Ensure keyboard navigation and ARIA labels
8. Consistent Spacing - Use Polaris spacing scale (gap="400")
9. SSR Compatible - Use data attributes for event handlers
10. 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.